Metadata-Version: 2.4
Name: mcp-ps-store
Version: 0.1.0
Summary: MCP server that exposes PlayStation Network gaming history for personal game recommendations
License: MIT
License-File: LICENSE
Keywords: mcp,model-context-protocol,playstation,psn,playstation-network,trophies
Author: Maksim Murzin
Author-email: wow_murzin@mail.ru
Requires-Python: >=3.11,<4.0
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Dist: dependency-injector (>=4.41.0,<5.0.0)
Requires-Dist: httpx (>=0.28.1,<0.29.0)
Requires-Dist: mcp (>=2.0.0,<3.0.0)
Requires-Dist: pydantic (>=2.11.7,<3.0.0)
Requires-Dist: pydantic-settings (>=2.1.0,<3.0.0)
Requires-Dist: python-dotenv (>=1.1.0,<2.0.0)
Requires-Dist: uvicorn[standard] (>=0.35.0,<0.36.0)
Project-URL: Homepage, https://github.com/murzin-ml/mcp-ps-store
Project-URL: Repository, https://github.com/murzin-ml/mcp-ps-store
Description-Content-Type: text/markdown

# mcp-ps-store

<!-- mcp-name: io.github.murzin-ml/mcp-ps-store -->

MCP server for the PlayStation Network (PSN): it exposes your own gaming history —
playtime, trophies, purchased library — so an AI assistant can recommend games from
real data instead of guesswork.

Русская версия: [README.ru.md](README.ru.md).

## About

PSN has no public API. This server talks to the same internal API the PlayStation mobile
app uses, authenticating with an NPSSO cookie taken from a browser session. Every request
is a read; nothing is ever written back to the account.

The layout follows a layered architecture: an API layer (MCP tools), a core layer
(services, repositories, DTOs), a DI container and an infrastructure layer.

### Core technologies

*   **Language:** Python 3.11+
*   **Protocol:** Model Context Protocol (`mcp`)
*   **HTTP client:** httpx (async)
*   **DI container:** `dependency-injector`
*   **Settings:** `pydantic-settings`
*   **Dependency management:** Poetry
*   **Testing:** Pytest, `pytest-asyncio`

## What it exposes

| Tool | What it is for |
| --- | --- |
| `psn_taste_profile` | The main one: a single digest — top games by hours, favourite franchises, playstyle habits (average session, share of deep dives, platinum rate), games close to 100%, games abandoned after an hour, and purchases never launched. Start here for any recommendation question. |
| `psn_library` | Filterable game list: search by title, sort by hours / last played / trophy progress, filter by platform, hours, dates and progress. |
| `psn_game_trophies` | Every trophy of one game: earned or not, date, rarity, share of players who have it. |
| `psn_owned_games` | What is already bought or claimed through PS Plus, with hours where known — so nothing already owned gets recommended. |
| `psn_recently_played` | What was launched most recently. |
| `psn_profile` | Online ID, PS Plus, trophy level, lifetime trophy counts. |
| `psn_refresh` | Drops the response cache (PSN answers are cached for 10 minutes). |

Plus a `recommend_games` prompt — a ready-made "build my profile and recommend games"
scenario that takes an optional steer such as "something short" or "co-op for two".

## Quick start

Python 3.11+ is required.

### 1. Install

With Poetry:

```bash
poetry install
```

Or with a plain virtualenv:

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

### 2. Sign in to PSN

1.  Sign in at https://www.playstation.com in a browser.
2.  Open https://ca.account.sony.com/api/v1/ssocookie — it returns `{"npsso":"..."}`.
3.  Copy the 64-character `npsso` value and run:

```bash
poetry run psn-login PASTE_NPSSO_HERE
```

Tokens go to `~/.mcp-ps-store/tokens.json` with `0600` permissions.

**About session lifetime.** The access token lives an hour and the refresh token only ten
days, but the NPSSO itself lives about two months. The NPSSO is therefore stored next to
the tokens, and the server re-authenticates on its own when the refresh token dies. In
practice one `psn-login` lasts about 60 days.

### 3. Check it works

```bash
poetry run psn-doctor
```

It prints the account name, how many games are visible and the top five by hours.

## Connecting a client

### Claude Code

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

### Claude Desktop

In `claude_desktop_config.json`:

```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 speaks stdio to local MCP servers, so it works the same way. Either run
`codex mcp add`, or add this to `~/.codex/config.toml`:

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

Check it with `/mcp` inside a Codex session.

### ChatGPT

ChatGPT cannot launch a local process. Custom connectors are added in Developer mode
(Settings → Apps → Advanced) and must be a **public HTTPS endpoint** speaking SSE or
Streamable HTTP. So the server has to be switched to HTTP transport and published:

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

Then expose `http://127.0.0.1:8000/mcp` over HTTPS — with OpenAI's Secure MCP Tunnel, or
a tunnel such as `cloudflared` / `ngrok` — and add the resulting URL as a custom connector.

**This publishes your PSN history to whoever finds the URL.** The server has no
authentication of its own, so put the tunnel behind auth, keep it running only while you
need it, and prefer Codex CLI if a local client will do.

## Configuration

All settings are read from the environment or a `.env` file (see `.env.example`).

| Variable | Default | Meaning |
| --- | --- | --- |
| `PSN_NPSSO` | — | NPSSO cookie. An alternative to `psn-login`: if set, the server signs in by itself. |
| `PSN_TOKENS_PATH` | `~/.mcp-ps-store/tokens.json` | Where tokens are cached. |
| `PSN_CACHE_TTL` | `600` | How long PSN responses are reused, in seconds. |
| `PSN_STORE_LOCALE` | `en-us` | Locale used in store.playstation.com links. |
| `PSN_REQUEST_TIMEOUT` | `30` | HTTP timeout for PSN requests, in seconds. |
| `PSN_MCP_TRANSPORT` | `stdio` | `stdio`, `streamable-http` or `sse`. |
| `PSN_MCP_HOST` | `127.0.0.1` | Bind address for the HTTP transports. |
| `PSN_MCP_PORT` | `8000` | Port for the HTTP transports. |

## Limitations

*   **Playtime exists only for PS4 / PS5 / PC versions.** PSN reports PS3 and Vita games
    with trophies only, so they appear with `hours: null`.
*   **There is no PS Store catalogue here.** The store is entirely client-side, and its
    GraphQL API only accepts persisted queries whose hashes Sony rotates on every deploy —
    keeping that working is not realistic. Recommendation candidates come from the model's
    own knowledge of games, while `psn_owned_games` stops it suggesting something already
    bought.
*   **The purchased library** goes through PSN's private GraphQL API. If Sony changes the
    query, that one tool stops working; everything else keeps running and the digest gains
    a `backlog_unavailable` note.
*   Playtime and trophies are joined by title, so a re-release can merge with the original
    when they share a trophy set. Editions, platform suffixes and roman numerals are
    normalised away on purpose — `Alan Wake II` and `Alan Wake 2` are one game.
*   The API is unofficial: Sony can change it at any time.

## Project structure

```
.
├── 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
```

## Development

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

## License

MIT — see [LICENSE](LICENSE).

