{"id":49418333,"url":"https://github.com/groupthink-dev/psn-blade-mcp","last_synced_at":"2026-04-29T04:12:24.963Z","repository":{"id":352166440,"uuid":"1203402078","full_name":"Groupthink-dev/psn-blade-mcp","owner":"Groupthink-dev","description":null,"archived":false,"fork":false,"pushed_at":"2026-04-28T04:57:28.000Z","size":111,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-28T06:32:40.659Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Groupthink-dev.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-07T02:26:24.000Z","updated_at":"2026-04-28T04:57:29.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/Groupthink-dev/psn-blade-mcp","commit_stats":null,"previous_names":["groupthink-dev/psn-blade-mcp"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/Groupthink-dev/psn-blade-mcp","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fpsn-blade-mcp","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fpsn-blade-mcp/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fpsn-blade-mcp/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fpsn-blade-mcp/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Groupthink-dev","download_url":"https://codeload.github.com/Groupthink-dev/psn-blade-mcp/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Groupthink-dev%2Fpsn-blade-mcp/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32410078,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-29T03:46:11.172Z","status":"ssl_error","status_checked_at":"2026-04-29T03:37:55.317Z","response_time":110,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-04-29T04:12:16.322Z","updated_at":"2026-04-29T04:12:20.659Z","avatar_url":"https://github.com/Groupthink-dev.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# PSN Blade MCP\n\nPlayStation Network MCP server for [Sidereal](https://sidereal.cc). Trophy tracking, game library, friends, presence, and messaging — all through token-efficient compact output designed for LLM consumption.\n\n## Why This Exists\n\nSeveral PSN libraries exist ([psn-api](https://github.com/achievements-app/psn-api), [PSNAWP](https://github.com/isFakeAccount/psnawp), [psn-php](https://github.com/Tustin/psn-php)). None are MCP servers. This blade bridges that gap:\n\n| | psn-api (npm) | PSNAWP (Python) | psn-php | **PSN Blade MCP** |\n|---|---|---|---|---|\n| **MCP protocol** | No | No | No | **Yes** — stdio + HTTP |\n| **Token-efficient output** | JSON blobs | Python objects | PHP arrays | **Compact text** — 3-5x fewer tokens |\n| **Auto token refresh** | No | Yes | Unknown | **Yes** (via PSNAWP) |\n| **Rate limiting** | No | Yes | No | **Yes** — 300/15min enforced |\n| **Write safety** | No gate | No gate | No gate | **Write-gated** — messaging and friend ops require explicit opt-in |\n| **Contract compliance** | N/A | N/A | N/A | **gaming-v1** — portable across PSN, Steam, Xbox |\n| **Sidereal integration** | None | None | None | **Full** — marketplace, packs, webhook triggers |\n\nBuilt on PSNAWP for its mature auth handling, rate limiting, and broadest API coverage (trophies + games + messaging + search + entitlements).\n\n## Quick Start\n\n### Install\n\n```bash\n# With uv (recommended)\nuv pip install psn-blade-mcp\n\n# Or from source\ngit clone https://github.com/groupthink-dev/psn-blade-mcp\ncd psn-blade-mcp\nmake install-dev\n```\n\n### Get Your NPSSO Token\n\n1. Log in at [store.playstation.com](https://store.playstation.com) in your browser\n2. Visit [ca.account.sony.com/api/v1/ssocookie](https://ca.account.sony.com/api/v1/ssocookie)\n3. Copy the `npsso` value from the JSON response\n\n\u003e **Security:** Use a dedicated PSN account for API access. Sony may restrict accounts with excessive API usage. The NPSSO token is equivalent to your password — never share it.\n\n### Configure\n\n```bash\n# Required\nexport PSN_NPSSO=\"your-npsso-token-here\"\n\n# Optional — enable messaging and friend management\nexport PSN_WRITE_ENABLED=true\n```\n\n### Run\n\n```bash\n# stdio transport (default — for Claude Code, Sidereal)\npsn-blade-mcp\n\n# HTTP transport (for remote/tunnel access)\nPSN_MCP_TRANSPORT=http PSN_MCP_PORT=8780 psn-blade-mcp\n```\n\n### Claude Code Configuration\n\nAdd to `~/.claude.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"psn\": {\n      \"type\": \"stdio\",\n      \"command\": \"psn-blade-mcp\",\n      \"env\": {\n        \"PSN_NPSSO\": \"your-npsso-token\"\n      }\n    }\n  }\n}\n```\n\n## Tools (17)\n\n### Profile \u0026 Social\n- **`psn_profile`** — User profile (name, avatar, PS Plus status)\n- **`psn_friends`** — Friends list\n- **`psn_presence`** — Online/in-game status\n- **`psn_search_users`** — Find users by name\n- **`psn_devices`** — Registered consoles\n\n### Trophies\n- **`psn_trophy_summary`** — Overall trophy level, tier, and counts\n- **`psn_trophies`** — Per-game trophy list with earned/locked status\n- **`psn_trophy_compare`** — Head-to-head trophy comparison\n- **`psn_trophy_groups`** — Base game + DLC trophy group breakdown\n\n### Games\n- **`psn_games`** — Game library with playtime stats\n- **`psn_games_recent`** — Recently played games\n- **`psn_entitlements`** — Purchase history\n- **`psn_game_details`** — Title metadata\n- **`psn_search_games`** — Search PlayStation Store\n\n### Messaging (write-gated)\n- **`psn_send_message`** — Send text message to a group\n- **`psn_friend_accept`** — Accept friend request\n- **`psn_friend_remove`** — Remove friend\n\n## Contract: `gaming-v1`\n\nThis MCP implements the `gaming-v1` Sidereal contract — a portable interface across gaming platforms. The same contract will be implemented by `steam-blade-mcp`, `xbox-blade-mcp`, and `retroachievements-blade-mcp`, enabling cross-platform pack skills.\n\n| Classification | Operations | Status |\n|---|---|---|\n| **Required** | profile, achievements, achievement_summary, games_played | Implemented |\n| **Recommended** | games_recent, friends, presence, search_users | Implemented |\n| **Optional** | achievement_compare, achievement_groups, games_purchased, devices, game_details, search_games | Implemented |\n| **Gated** | send_message, friend_add, friend_remove | Implemented (write-gated) |\n\n## Architecture\n\n```\npsn-blade-mcp/\n├── src/psn_blade_mcp/\n│   ├── server.py       # FastMCP tool definitions (17 tools)\n│   ├── client.py       # PSNAWP wrapper with error handling\n│   ├── models.py       # Constants, write-gate, shared types\n│   ├── formatters.py   # Token-efficient compact text output\n│   └── auth.py         # Bearer token middleware (HTTP transport)\n├── tests/              # pytest + asyncio (mocked, no live API)\n├── sidereal-plugin.yaml  # Marketplace manifest\n└── SKILL.md            # LLM usage guide\n```\n\n**Key design decisions:**\n- **PSNAWP as client layer** — proven auth handling, auto token refresh, built-in rate limiting (300 req/15min), typed exceptions for every HTTP status\n- **Compact text output** — all formatters return pipe-delimited strings, not JSON. 3-5x fewer tokens than raw API responses\n- **Lazy client initialization** — PSN auth only happens on first tool call, not server startup\n- **Write-gated operations** — messaging and friend management require explicit `PSN_WRITE_ENABLED=true`\n\n## Rate Limiting\n\nSony enforces ~300 requests per 15-minute window. PSNAWP's built-in rate limiter (1 request per 3 seconds via SQLite-backed bucket) prevents exceeding this. The MCP server adds no additional rate limiting — PSNAWP handles it transparently.\n\nIf rate limited, the server returns a clear error: `\"Rate limited by PSN — wait a few minutes before retrying.\"`\n\n## Token Lifecycle\n\n| Token | Lifetime | Refresh |\n|---|---|---|\n| NPSSO | Browser session (~24h) | Manual — re-visit ssocookie URL |\n| Access token | ~60 minutes | Automatic (PSNAWP handles transparently) |\n| Refresh token | ~2 months | Automatic (PSNAWP handles transparently) |\n\nWhen your NPSSO expires, the server returns an auth error with instructions to regenerate it.\n\n## Development\n\n```bash\nmake install-dev     # Install with dev/test dependencies\nmake test            # Run unit tests\nmake test-cov        # Tests with coverage report\nmake check           # Lint + format + type-check\nmake run             # Run the MCP server\n```\n\n## Disclaimer\n\nThis project uses Sony's **unofficial, undocumented** PlayStation Network API via [PSNAWP](https://github.com/isFakeAccount/psnawp). There is no official Sony API for PSN data. Sony may change or break these endpoints at any time. Use at your own risk and consider using a dedicated PSN account.\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fpsn-blade-mcp","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgroupthink-dev%2Fpsn-blade-mcp","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgroupthink-dev%2Fpsn-blade-mcp/lists"}