psn-mcp 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Timothy Peterson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# psn-mcp
+
+An [MCP](https://modelcontextprotocol.io) (Model Context Protocol) server for interfacing with the PlayStation Network. Lets MCP clients like Claude look up PSN profiles, friends, online presence, trophies, and play history.
+
+The PSN API layer is written from scratch in TypeScript on Node's built-in `fetch` — no PSN client dependencies. It authenticates the same way the official PlayStation mobile app does and talks directly to Sony's `m.np.playstation.com` API.
+
+## Requirements
+
+- Node.js 18+
+- A PlayStation Network account and its **NPSSO token** (see below)
+
+## Getting your NPSSO token
+
+1. Sign in at [playstation.com](https://www.playstation.com).
+2. In the same browser, open <https://ca.account.sony.com/api/v1/ssocookie>.
+3. Copy the 64-character `npsso` value from the JSON response.
+
+The server exchanges the NPSSO for an OAuth access token on first use and refreshes it automatically. NPSSO tokens expire after about two months; when tools start failing with an auth error, fetch a fresh one.
+
+> **Note:** this uses your personal account session. What you can see (other users' friends, presence, play history) is governed by normal PSN privacy settings.
+
+## Usage with an MCP client
+
+No installation needed — run it with `npx`. Add to your client's MCP configuration (e.g. `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "psn": {
+      "command": "npx",
+      "args": ["-y", "psn-mcp"],
+      "env": {
+        "PSN_NPSSO": "<your npsso token>"
+      }
+    }
+  }
+}
+```
+
+Or for Claude Code:
+
+```sh
+claude mcp add psn --env PSN_NPSSO=<your npsso token> -- npx -y psn-mcp
+```
+
+## Tools
+
+| Tool | Description |
+| --- | --- |
+| `psn_get_profile` | Profile for a user: online id, about-me, avatars, PS Plus status |
+| `psn_search_players` | Search PSN players by name; returns online ids and account ids |
+| `psn_get_friends` | A user's friends list, resolved to profiles |
+| `psn_get_presence` | Online status, current platform, and the game being played |
+| `psn_get_trophy_summary` | Trophy level, tier, and total trophy counts |
+| `psn_get_trophy_titles` | Games with trophy progress, most recently played first |
+| `psn_get_title_trophies` | Full trophy list defined for a game (names, types, groups) |
+| `psn_get_earned_trophies` | Which trophies a user earned in a game, with timestamps and rarity |
+| `psn_get_played_games` | Played PS4/PS5 games with play counts and durations |
+
+Every user-scoped tool accepts `"me"` (the authenticated account), a PSN online id (username), or a numeric account id — online ids are resolved automatically.
+
+For PS5 titles pass `npServiceName: "trophy2"`; for PS4 and earlier use `"trophy"`. `psn_get_trophy_titles` reports the right value per game.
+
+## Architecture
+
+```
+src/
+  index.ts        Entry point: stdio MCP server wiring
+  tools.ts        MCP tool definitions (zod schemas -> PSN API calls)
+  psn/
+    auth.ts       NPSSO -> OAuth code -> access token exchange, auto-refresh
+    http.ts       Authenticated JSON client for m.np.playstation.com
+    api.ts        Typed endpoint wrappers (profiles, trophies, games, search)
+    types.ts      PSN API response types
+```
+
+Authentication is lazy: the server starts and lists tools without credentials; the token exchange happens on the first tool call. Access tokens are refreshed ahead of expiry, falling back to a full NPSSO re-exchange if the refresh token has expired.
+
+## Disclaimer
+
+This project uses undocumented PSN endpoints and is not affiliated with or endorsed by Sony Interactive Entertainment. Use at your own risk.

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TokenManager } from "./psn/auth.js";
+import { PsnHttpClient } from "./psn/http.js";
+import { PsnApi } from "./psn/api.js";
+import { registerTools } from "./tools.js";
+async function main() {
+    const npsso = process.env.PSN_NPSSO ?? "";
+    if (!npsso) {
+        // stdout is reserved for the MCP protocol; diagnostics go to stderr.
+        console.error("warning: PSN_NPSSO is not set - tools will fail until it is configured.\n" +
+            "Sign in at https://www.playstation.com, then copy the token from " +
+            "https://ca.account.sony.com/api/v1/ssocookie");
+    }
+    // Auth is lazy: the token exchange happens on the first tool call, so the
+    // server starts (and lists tools) even before credentials are configured.
+    const psn = new PsnApi(new PsnHttpClient(new TokenManager(npsso || "unset")));
+    const server = new McpServer({ name: "psn-mcp", version: "0.1.0" });
+    registerTools(server, psn);
+    await server.connect(new StdioServerTransport());
+    console.error("psn-mcp server running on stdio");
+}
+main().catch((error) => {
+    console.error("fatal:", error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,oBAAoB,EAAE,MAAM,2CAA2C,CAAC;AACjF,OAAO,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC7C,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,KAAK,UAAU,IAAI;IACjB,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,IAAI,EAAE,CAAC;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,qEAAqE;QACrE,OAAO,CAAC,KAAK,CACX,2EAA2E;YACzE,mEAAmE;YACnE,8CAA8C,CACjD,CAAC;IACJ,CAAC;IAED,0EAA0E;IAC1E,0EAA0E;IAC1E,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC,IAAI,aAAa,CAAC,IAAI,YAAY,CAAC,KAAK,IAAI,OAAO,CAAC,CAAC,CAAC,CAAC;IAE9E,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,SAAS,EAAE,OAAO,EAAE,OAAO,EAAE,CAAC,CAAC;IACpE,aAAa,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;IAE3B,MAAM,MAAM,CAAC,OAAO,CAAC,IAAI,oBAAoB,EAAE,CAAC,CAAC;IACjD,OAAO,CAAC,KAAK,CAAC,iCAAiC,CAAC,CAAC;AACnD,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;IAC/B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/psn/api.d.ts

@@ -0,0 +1,36 @@
+import { PsnHttpClient } from "./http.js";
+import type { BasicPresence, FriendsResponse, PlayedGamesResponse, TrophiesResponse, TrophySummary, TrophyTitlesResponse, UniversalSearchResponse, UserProfile } from "./types.js";
+export type NpServiceName = "trophy" | "trophy2";
+/**
+ * Typed wrappers around the PSN mobile API endpoints.
+ *
+ * User-scoped endpoints accept the literal string "me" (the authenticated
+ * account) or a numeric account id. Use {@link resolveAccountId} to turn an
+ * online id (PSN username) into an account id first.
+ */
+export declare class PsnApi {
+    private readonly http;
+    constructor(http: PsnHttpClient);
+    getProfile(accountId: string): Promise<UserProfile>;
+    searchPlayers(searchTerm: string, limit?: number): Promise<UniversalSearchResponse>;
+    /**
+     * Resolves a user reference to an account id. Accepts "me", a numeric
+     * account id (passed through), or an online id which is looked up via
+     * universal search and matched exactly (case-insensitively).
+     */
+    resolveAccountId(user: string): Promise<string>;
+    getFriends(accountId: string, limit?: number, offset?: number): Promise<FriendsResponse>;
+    getBasicPresence(accountId: string): Promise<{
+        basicPresence: BasicPresence;
+    }>;
+    getBasicPresences(accountIds: string[]): Promise<{
+        basicPresences: BasicPresence[];
+    }>;
+    getTrophySummary(accountId: string): Promise<TrophySummary>;
+    getTrophyTitles(accountId: string, limit?: number, offset?: number): Promise<TrophyTitlesResponse>;
+    /** Trophy definitions for a title (names, descriptions, types). */
+    getTitleTrophies(npCommunicationId: string, npServiceName: NpServiceName, trophyGroupId?: string, limit?: number, offset?: number): Promise<TrophiesResponse>;
+    /** A user's earned/unearned status for each trophy in a title. */
+    getEarnedTrophies(accountId: string, npCommunicationId: string, npServiceName: NpServiceName, trophyGroupId?: string, limit?: number, offset?: number): Promise<TrophiesResponse>;
+    getPlayedGames(accountId: string, limit?: number, offset?: number): Promise<PlayedGamesResponse>;
+}

package/dist/psn/api.js

@@ -0,0 +1,87 @@
+/**
+ * Typed wrappers around the PSN mobile API endpoints.
+ *
+ * User-scoped endpoints accept the literal string "me" (the authenticated
+ * account) or a numeric account id. Use {@link resolveAccountId} to turn an
+ * online id (PSN username) into an account id first.
+ */
+export class PsnApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    // ---- Users -------------------------------------------------------------
+    getProfile(accountId) {
+        return this.http.request(`/userProfile/v1/internal/users/${encodeURIComponent(accountId)}/profiles`);
+    }
+    searchPlayers(searchTerm, limit = 20) {
+        return this.http.request("/search/v1/universalSearch", {
+            method: "POST",
+            body: {
+                searchTerm,
+                domainRequests: [
+                    {
+                        domain: "SocialAllAccounts",
+                        pagination: { cursor: "", pageSize: limit },
+                    },
+                ],
+            },
+        });
+    }
+    /**
+     * Resolves a user reference to an account id. Accepts "me", a numeric
+     * account id (passed through), or an online id which is looked up via
+     * universal search and matched exactly (case-insensitively).
+     */
+    async resolveAccountId(user) {
+        const trimmed = user.trim();
+        if (trimmed === "me" || /^\d+$/.test(trimmed))
+            return trimmed;
+        const search = await this.searchPlayers(trimmed, 20);
+        const results = search.domainResponses[0]?.results ?? [];
+        const match = results.find((r) => r.socialMetadata?.onlineId?.toLowerCase() === trimmed.toLowerCase());
+        if (!match?.socialMetadata?.accountId) {
+            throw new Error(`No PSN user found with online id "${trimmed}". ` +
+                "Try psn_search_players to find the exact online id.");
+        }
+        return match.socialMetadata.accountId;
+    }
+    getFriends(accountId, limit = 100, offset = 0) {
+        return this.http.request(`/userProfile/v1/internal/users/${encodeURIComponent(accountId)}/friends`, { query: { limit, offset } });
+    }
+    getBasicPresence(accountId) {
+        return this.http.request(`/userProfile/v1/internal/users/${encodeURIComponent(accountId)}/basicPresences`, { query: { type: "primary" } });
+    }
+    getBasicPresences(accountIds) {
+        return this.http.request("/userProfile/v1/internal/users/basicPresences", { query: { type: "primary", accountIds: accountIds.join(",") } });
+    }
+    // ---- Trophies ----------------------------------------------------------
+    getTrophySummary(accountId) {
+        return this.http.request(`/trophy/v1/users/${encodeURIComponent(accountId)}/trophySummary`);
+    }
+    getTrophyTitles(accountId, limit = 100, offset = 0) {
+        return this.http.request(`/trophy/v1/users/${encodeURIComponent(accountId)}/trophyTitles`, { query: { limit, offset } });
+    }
+    /** Trophy definitions for a title (names, descriptions, types). */
+    getTitleTrophies(npCommunicationId, npServiceName, trophyGroupId = "all", limit = 200, offset = 0) {
+        return this.http.request(`/trophy/v1/npCommunicationIds/${encodeURIComponent(npCommunicationId)}` +
+            `/trophyGroups/${encodeURIComponent(trophyGroupId)}/trophies`, { query: { npServiceName, limit, offset } });
+    }
+    /** A user's earned/unearned status for each trophy in a title. */
+    getEarnedTrophies(accountId, npCommunicationId, npServiceName, trophyGroupId = "all", limit = 200, offset = 0) {
+        return this.http.request(`/trophy/v1/users/${encodeURIComponent(accountId)}` +
+            `/npCommunicationIds/${encodeURIComponent(npCommunicationId)}` +
+            `/trophyGroups/${encodeURIComponent(trophyGroupId)}/trophies`, { query: { npServiceName, limit, offset } });
+    }
+    // ---- Game library ------------------------------------------------------
+    getPlayedGames(accountId, limit = 50, offset = 0) {
+        return this.http.request(`/gamelist/v2/users/${encodeURIComponent(accountId)}/titles`, {
+            query: {
+                categories: "ps4_game,ps5_native_game,pspc_game",
+                limit,
+                offset,
+            },
+        });
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/psn/api.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.js","sourceRoot":"","sources":["../../src/psn/api.ts"],"names":[],"mappings":"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"}

package/dist/psn/auth.d.ts

@@ -0,0 +1,39 @@
+/**
+ * PlayStation Network authentication.
+ *
+ * PSN has no public developer API. Access works the same way the official
+ * PlayStation mobile app authenticates: an NPSSO token (obtained by the user
+ * from their browser session) is exchanged for an OAuth authorization code,
+ * which is then exchanged for a bearer access token + refresh token.
+ *
+ * The client id/secret below are the public constants baked into the
+ * official PlayStation Android app and are required for the token exchange.
+ */
+export interface TokenSet {
+    accessToken: string;
+    /** Epoch ms after which the access token is no longer valid. */
+    expiresAt: number;
+    refreshToken: string;
+    /** Epoch ms after which the refresh token is no longer valid. */
+    refreshExpiresAt: number;
+}
+export declare class PsnAuthError extends Error {
+    constructor(message: string);
+}
+/** Full NPSSO -> authorization code -> access token exchange. */
+export declare function authenticateWithNpsso(npsso: string): Promise<TokenSet>;
+export declare function refreshTokens(refreshToken: string): Promise<TokenSet>;
+/**
+ * Manages the token lifecycle: authenticates lazily on first use, refreshes
+ * ahead of expiry, and falls back to a fresh NPSSO exchange if the refresh
+ * token itself has expired.
+ */
+export declare class TokenManager {
+    private readonly npsso;
+    private tokens;
+    private pending;
+    constructor(npsso: string);
+    /** Returns a valid access token, authenticating or refreshing as needed. */
+    getAccessToken(): Promise<string>;
+    private renew;
+}

package/dist/psn/auth.js

@@ -0,0 +1,134 @@
+/**
+ * PlayStation Network authentication.
+ *
+ * PSN has no public developer API. Access works the same way the official
+ * PlayStation mobile app authenticates: an NPSSO token (obtained by the user
+ * from their browser session) is exchanged for an OAuth authorization code,
+ * which is then exchanged for a bearer access token + refresh token.
+ *
+ * The client id/secret below are the public constants baked into the
+ * official PlayStation Android app and are required for the token exchange.
+ */
+const AUTH_BASE = "https://ca.account.sony.com/api/authz/v3/oauth";
+const CLIENT_ID = "09515159-7237-4370-9b40-3806e67c0891";
+const CLIENT_SECRET = "ucPjka5tntB2KqsP";
+const REDIRECT_URI = "com.scee.psxandroid.scecompcall://redirect";
+const SCOPE = "psn:mobile.v2.core psn:clientapp";
+export class PsnAuthError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "PsnAuthError";
+    }
+}
+/** Exchange an NPSSO token for an OAuth authorization code. */
+async function exchangeNpssoForCode(npsso) {
+    const params = new URLSearchParams({
+        access_type: "offline",
+        client_id: CLIENT_ID,
+        redirect_uri: REDIRECT_URI,
+        response_type: "code",
+        scope: SCOPE,
+    });
+    const res = await fetch(`${AUTH_BASE}/authorize?${params}`, {
+        method: "GET",
+        headers: { Cookie: `npsso=${npsso}` },
+        redirect: "manual",
+    });
+    const location = res.headers.get("location");
+    if (!location || !location.includes("code=")) {
+        throw new PsnAuthError("Failed to obtain an authorization code from the NPSSO token. " +
+            "The token is most likely expired or invalid - fetch a fresh one from " +
+            "https://ca.account.sony.com/api/v1/ssocookie while signed in to PlayStation.");
+    }
+    const code = new URL(location).searchParams.get("code");
+    if (!code) {
+        throw new PsnAuthError("Authorization redirect did not contain a code parameter.");
+    }
+    return code;
+}
+async function requestToken(body) {
+    const res = await fetch(`${AUTH_BASE}/token`, {
+        method: "POST",
+        headers: {
+            Authorization: `Basic ${Buffer.from(`${CLIENT_ID}:${CLIENT_SECRET}`).toString("base64")}`,
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body,
+    });
+    if (!res.ok) {
+        const text = await res.text().catch(() => "");
+        throw new PsnAuthError(`Token request failed with HTTP ${res.status}: ${text}`);
+    }
+    const data = (await res.json());
+    const now = Date.now();
+    return {
+        accessToken: data.access_token,
+        expiresAt: now + data.expires_in * 1000,
+        refreshToken: data.refresh_token,
+        refreshExpiresAt: now + data.refresh_token_expires_in * 1000,
+    };
+}
+/** Full NPSSO -> authorization code -> access token exchange. */
+export async function authenticateWithNpsso(npsso) {
+    const code = await exchangeNpssoForCode(npsso);
+    return requestToken(new URLSearchParams({
+        code,
+        redirect_uri: REDIRECT_URI,
+        grant_type: "authorization_code",
+        token_format: "jwt",
+    }));
+}
+export async function refreshTokens(refreshToken) {
+    return requestToken(new URLSearchParams({
+        refresh_token: refreshToken,
+        grant_type: "refresh_token",
+        scope: SCOPE,
+        token_format: "jwt",
+    }));
+}
+/**
+ * Manages the token lifecycle: authenticates lazily on first use, refreshes
+ * ahead of expiry, and falls back to a fresh NPSSO exchange if the refresh
+ * token itself has expired.
+ */
+export class TokenManager {
+    npsso;
+    tokens = null;
+    pending = null;
+    constructor(npsso) {
+        this.npsso = npsso;
+        if (!npsso) {
+            throw new PsnAuthError("No NPSSO token configured. Set the PSN_NPSSO environment variable. " +
+                "Sign in at https://www.playstation.com, then visit " +
+                "https://ca.account.sony.com/api/v1/ssocookie to copy your token.");
+        }
+    }
+    /** Returns a valid access token, authenticating or refreshing as needed. */
+    async getAccessToken() {
+        // 60s of headroom so a token can't expire mid-request.
+        const margin = 60_000;
+        if (this.tokens && this.tokens.expiresAt - margin > Date.now()) {
+            return this.tokens.accessToken;
+        }
+        if (!this.pending) {
+            this.pending = this.renew().finally(() => {
+                this.pending = null;
+            });
+        }
+        this.tokens = await this.pending;
+        return this.tokens.accessToken;
+    }
+    async renew() {
+        const margin = 60_000;
+        if (this.tokens && this.tokens.refreshExpiresAt - margin > Date.now()) {
+            try {
+                return await refreshTokens(this.tokens.refreshToken);
+            }
+            catch {
+                // Refresh failed (revoked, etc.) - fall through to a full re-auth.
+            }
+        }
+        return authenticateWithNpsso(this.npsso);
+    }
+}
+//# sourceMappingURL=auth.js.map

package/dist/psn/auth.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.js","sourceRoot":"","sources":["../../src/psn/auth.ts"],"names":[],"mappings":"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"}

package/dist/psn/http.d.ts

@@ -0,0 +1,21 @@
+import type { TokenManager } from "./auth.js";
+export declare class PsnApiError extends Error {
+    readonly status: number;
+    readonly body?: unknown | undefined;
+    constructor(message: string, status: number, body?: unknown | undefined);
+}
+export interface RequestOptions {
+    method?: "GET" | "POST";
+    /** Query string parameters; undefined values are dropped. */
+    query?: Record<string, string | number | boolean | undefined>;
+    /** JSON body for POST requests. */
+    body?: unknown;
+    /** Extra headers merged over the defaults. */
+    headers?: Record<string, string>;
+}
+/** Authenticated JSON client for the m.np.playstation.com API. */
+export declare class PsnHttpClient {
+    private readonly tokens;
+    constructor(tokens: TokenManager);
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+}

package/dist/psn/http.js

@@ -0,0 +1,58 @@
+const API_BASE = "https://m.np.playstation.com/api";
+export class PsnApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = "PsnApiError";
+    }
+}
+/** Authenticated JSON client for the m.np.playstation.com API. */
+export class PsnHttpClient {
+    tokens;
+    constructor(tokens) {
+        this.tokens = tokens;
+    }
+    async request(path, options = {}) {
+        const accessToken = await this.tokens.getAccessToken();
+        const url = new URL(`${API_BASE}${path}`);
+        for (const [key, value] of Object.entries(options.query ?? {})) {
+            if (value !== undefined)
+                url.searchParams.set(key, String(value));
+        }
+        const res = await fetch(url, {
+            method: options.method ?? "GET",
+            headers: {
+                Authorization: `Bearer ${accessToken}`,
+                "Accept-Language": "en-US",
+                ...(options.body !== undefined ? { "Content-Type": "application/json" } : {}),
+                ...options.headers,
+            },
+            body: options.body !== undefined ? JSON.stringify(options.body) : undefined,
+        });
+        if (!res.ok) {
+            let body;
+            let message = `PSN API request to ${path} failed with HTTP ${res.status}`;
+            try {
+                body = await res.json();
+                const err = body.error;
+                if (err?.message)
+                    message += `: ${err.message}`;
+            }
+            catch {
+                // Non-JSON error body; keep the generic message.
+            }
+            if (res.status === 403) {
+                message +=
+                    ". The target profile may be private, or your account may not be allowed to view it.";
+            }
+            throw new PsnApiError(message, res.status, body);
+        }
+        // A few endpoints return 204 / empty bodies.
+        const text = await res.text();
+        return (text ? JSON.parse(text) : {});
+    }
+}
+//# sourceMappingURL=http.js.map

package/dist/psn/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../../src/psn/http.ts"],"names":[],"mappings":"AAEA,MAAM,QAAQ,GAAG,kCAAkC,CAAC;AAEpD,MAAM,OAAO,WAAY,SAAQ,KAAK;IAGlB;IACA;IAHlB,YACE,OAAe,EACC,MAAc,EACd,IAAc;QAE9B,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,WAAM,GAAN,MAAM,CAAQ;QACd,SAAI,GAAJ,IAAI,CAAU;QAG9B,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;IAC5B,CAAC;CACF;AAYD,kEAAkE;AAClE,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,MAAoB;QAApB,WAAM,GAAN,MAAM,CAAc;IAAG,CAAC;IAErD,KAAK,CAAC,OAAO,CAAI,IAAY,EAAE,UAA0B,EAAE;QACzD,MAAM,WAAW,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,cAAc,EAAE,CAAC;QAEvD,MAAM,GAAG,GAAG,IAAI,GAAG,CAAC,GAAG,QAAQ,GAAG,IAAI,EAAE,CAAC,CAAC;QAC1C,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,KAAK,IAAI,EAAE,CAAC,EAAE,CAAC;YAC/D,IAAI,KAAK,KAAK,SAAS;gBAAE,GAAG,CAAC,YAAY,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;QACpE,CAAC;QAED,MAAM,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,EAAE;YAC3B,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,KAAK;YAC/B,OAAO,EAAE;gBACP,aAAa,EAAE,UAAU,WAAW,EAAE;gBACtC,iBAAiB,EAAE,OAAO;gBAC1B,GAAG,CAAC,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBAC7E,GAAG,OAAO,CAAC,OAAO;aACnB;YACD,IAAI,EAAE,OAAO,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;SAC5E,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC;YACZ,IAAI,IAAa,CAAC;YAClB,IAAI,OAAO,GAAG,sBAAsB,IAAI,qBAAqB,GAAG,CAAC,MAAM,EAAE,CAAC;YAC1E,IAAI,CAAC;gBACH,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;gBACxB,MAAM,GAAG,GAAI,IAAyC,CAAC,KAAK,CAAC;gBAC7D,IAAI,GAAG,EAAE,OAAO;oBAAE,OAAO,IAAI,KAAK,GAAG,CAAC,OAAO,EAAE,CAAC;YAClD,CAAC;YAAC,MAAM,CAAC;gBACP,iDAAiD;YACnD,CAAC;YACD,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG,EAAE,CAAC;gBACvB,OAAO;oBACL,qFAAqF,CAAC;YAC1F,CAAC;YACD,MAAM,IAAI,WAAW,CAAC,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;QACnD,CAAC;QAED,6CAA6C;QAC7C,MAAM,IAAI,GAAG,MAAM,GAAG,CAAC,IAAI,EAAE,CAAC;QAC9B,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAM,CAAC;IAC7C,CAAC;CACF"}

package/dist/psn/types.d.ts

@@ -0,0 +1,127 @@
+/** Shapes returned by the PSN API. Fields are optional where PSN omits them. */
+export interface UserProfile {
+    onlineId: string;
+    accountId?: string;
+    aboutMe?: string;
+    avatars?: Array<{
+        size: string;
+        url: string;
+    }>;
+    languages?: string[];
+    isPlus?: boolean;
+    isOfficiallyVerified?: boolean;
+    isMe?: boolean;
+}
+export interface UniversalSearchResult {
+    domain: string;
+    domainResponse: {
+        totalResultCount: number;
+        results?: Array<{
+            id: string;
+            socialMetadata?: {
+                accountId: string;
+                onlineId: string;
+                verifiedUserName?: string;
+                avatarUrl?: string;
+                isPsPlus?: boolean;
+                relationshipState?: string;
+            };
+        }>;
+    };
+}
+export interface UniversalSearchResponse {
+    domainResponses: UniversalSearchResult["domainResponse"][];
+}
+export interface FriendsResponse {
+    friends: string[];
+    totalItemCount: number;
+    nextOffset?: number;
+    previousOffset?: number;
+}
+export interface BasicPresence {
+    accountId?: string;
+    availability?: string;
+    lastAvailableDate?: string;
+    primaryPlatformInfo?: {
+        onlineStatus?: string;
+        platform?: string;
+        lastOnlineDate?: string;
+    };
+    gameTitleInfoList?: Array<{
+        npTitleId: string;
+        titleName: string;
+        format?: string;
+        launchPlatform?: string;
+        conceptIconUrl?: string;
+    }>;
+}
+export interface TrophySummary {
+    accountId: string;
+    trophyLevel: number;
+    progress: number;
+    tier: number;
+    earnedTrophies: TrophyCounts;
+}
+export interface TrophyCounts {
+    bronze: number;
+    silver: number;
+    gold: number;
+    platinum: number;
+}
+export interface TrophyTitle {
+    npServiceName: "trophy" | "trophy2";
+    npCommunicationId: string;
+    trophyTitleName: string;
+    trophyTitleDetail?: string;
+    trophyTitleIconUrl?: string;
+    trophyTitlePlatform: string;
+    hasTrophyGroups: boolean;
+    definedTrophies: TrophyCounts;
+    progress: number;
+    earnedTrophies: TrophyCounts;
+    hiddenFlag?: boolean;
+    lastUpdatedDateTime: string;
+}
+export interface TrophyTitlesResponse {
+    trophyTitles: TrophyTitle[];
+    totalItemCount: number;
+    nextOffset?: number;
+}
+export interface Trophy {
+    trophyId: number;
+    trophyHidden: boolean;
+    trophyType: "bronze" | "silver" | "gold" | "platinum";
+    trophyName?: string;
+    trophyDetail?: string;
+    trophyIconUrl?: string;
+    trophyGroupId?: string;
+    earned?: boolean;
+    earnedDateTime?: string;
+    trophyEarnedRate?: string;
+    trophyRare?: number;
+    progress?: string;
+    progressRate?: number;
+}
+export interface TrophiesResponse {
+    trophySetVersion: string;
+    hasTrophyGroups: boolean;
+    trophies: Trophy[];
+    totalItemCount: number;
+    nextOffset?: number;
+}
+export interface PlayedGame {
+    titleId: string;
+    name: string;
+    localizedName?: string;
+    imageUrl?: string;
+    category: string;
+    playCount?: number;
+    firstPlayedDateTime?: string;
+    lastPlayedDateTime?: string;
+    playDuration?: string;
+}
+export interface PlayedGamesResponse {
+    titles: PlayedGame[];
+    totalItemCount: number;
+    nextOffset?: number;
+}

package/dist/psn/types.js

@@ -0,0 +1,3 @@
+/** Shapes returned by the PSN API. Fields are optional where PSN omits them. */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/psn/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/psn/types.ts"],"names":[],"mappings":"AAAA,gFAAgF"}

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { PsnApi } from "./psn/api.js";
+export declare function registerTools(server: McpServer, psn: PsnApi): void;

package/dist/tools.js

@@ -0,0 +1,151 @@
+import { z } from "zod";
+const userParam = z
+    .string()
+    .describe('PSN user: "me" for the authenticated account, a PSN online id (username), or a numeric account id.');
+const npServiceNameParam = z
+    .enum(["trophy", "trophy2"])
+    .describe('Trophy service: "trophy2" for PS5/PS VR2 titles, "trophy" for PS4 and earlier. ' +
+    "Use the npServiceName reported by psn_get_trophy_titles.");
+function jsonResult(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function errorResult(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { content: [{ type: "text", text: message }], isError: true };
+}
+/** Wraps a handler so PSN/auth failures surface as MCP tool errors, not crashes. */
+function handle(fn) {
+    return async (args) => {
+        try {
+            return jsonResult(await fn(args));
+        }
+        catch (error) {
+            return errorResult(error);
+        }
+    };
+}
+export function registerTools(server, psn) {
+    server.registerTool("psn_get_profile", {
+        title: "Get PSN profile",
+        description: "Get a PlayStation Network user's profile: online id, about-me, avatars, " +
+            "languages, and PS Plus / verification status.",
+        inputSchema: { user: userParam },
+    }, handle(async ({ user }) => psn.getProfile(await psn.resolveAccountId(user))));
+    server.registerTool("psn_search_players", {
+        title: "Search PSN players",
+        description: "Search PlayStation Network for players by name. Returns matching online ids, " +
+            "account ids, and avatars. Useful for finding a user's account id.",
+        inputSchema: {
+            query: z.string().describe("Name or online id to search for."),
+            limit: z.number().int().min(1).max(50).default(20).describe("Max results."),
+        },
+    }, handle(async ({ query, limit }) => {
+        const res = await psn.searchPlayers(query, limit);
+        const results = res.domainResponses[0]?.results ?? [];
+        return results
+            .map((r) => r.socialMetadata)
+            .filter(Boolean)
+            .map((m) => ({
+            onlineId: m.onlineId,
+            accountId: m.accountId,
+            verifiedUserName: m.verifiedUserName || undefined,
+            avatarUrl: m.avatarUrl,
+            isPsPlus: m.isPsPlus,
+        }));
+    }));
+    server.registerTool("psn_get_friends", {
+        title: "Get PSN friends",
+        description: "List a user's PSN friends with their profiles. Friends lists other than your " +
+            "own are only visible if that user's privacy settings allow it.",
+        inputSchema: {
+            user: userParam.default("me"),
+            limit: z.number().int().min(1).max(500).default(50).describe("Max friends to return."),
+            offset: z.number().int().min(0).default(0).describe("Pagination offset."),
+        },
+    }, handle(async ({ user, limit, offset }) => {
+        const accountId = await psn.resolveAccountId(user);
+        const friends = await psn.getFriends(accountId, limit, offset);
+        // The friends endpoint returns bare account ids; resolve them to profiles.
+        const profiles = await Promise.all(friends.friends.map(async (id) => {
+            try {
+                const profile = await psn.getProfile(id);
+                return { accountId: id, onlineId: profile.onlineId, isPlus: profile.isPlus };
+            }
+            catch {
+                return { accountId: id };
+            }
+        }));
+        return {
+            totalItemCount: friends.totalItemCount,
+            nextOffset: friends.nextOffset,
+            friends: profiles,
+        };
+    }));
+    server.registerTool("psn_get_presence", {
+        title: "Get PSN presence",
+        description: "Get a user's current online status: whether they are online, on which " +
+            "platform (PS5/PS4), what game they are playing, and when they were last online.",
+        inputSchema: { user: userParam.default("me") },
+    }, handle(async ({ user }) => psn.getBasicPresence(await psn.resolveAccountId(user))));
+    server.registerTool("psn_get_trophy_summary", {
+        title: "Get trophy summary",
+        description: "Get a user's overall trophy summary: trophy level, tier, progress to next " +
+            "level, and total bronze/silver/gold/platinum counts.",
+        inputSchema: { user: userParam.default("me") },
+    }, handle(async ({ user }) => psn.getTrophySummary(await psn.resolveAccountId(user))));
+    server.registerTool("psn_get_trophy_titles", {
+        title: "Get trophy titles",
+        description: "List the games a user has earned trophies in, ordered by most recently " +
+            "played, with per-game progress and earned counts. Returns each game's " +
+            "npCommunicationId and npServiceName for use with the trophy detail tools.",
+        inputSchema: {
+            user: userParam.default("me"),
+            limit: z.number().int().min(1).max(800).default(50).describe("Max titles to return."),
+            offset: z.number().int().min(0).default(0).describe("Pagination offset."),
+        },
+    }, handle(async ({ user, limit, offset }) => psn.getTrophyTitles(await psn.resolveAccountId(user), limit, offset)));
+    server.registerTool("psn_get_title_trophies", {
+        title: "Get a game's trophy list",
+        description: "Get the full trophy list defined for a game (names, descriptions, types, " +
+            "groups). Get npCommunicationId and npServiceName from psn_get_trophy_titles.",
+        inputSchema: {
+            npCommunicationId: z
+                .string()
+                .describe('Trophy set id, e.g. "NPWR20188_00".'),
+            npServiceName: npServiceNameParam,
+            trophyGroupId: z
+                .string()
+                .default("all")
+                .describe('Trophy group: "all", "default" (base game), or "001", "002"... for DLC.'),
+            limit: z.number().int().min(1).max(500).default(200),
+            offset: z.number().int().min(0).default(0),
+        },
+    }, handle(({ npCommunicationId, npServiceName, trophyGroupId, limit, offset }) => psn.getTitleTrophies(npCommunicationId, npServiceName, trophyGroupId, limit, offset)));
+    server.registerTool("psn_get_earned_trophies", {
+        title: "Get a user's earned trophies for a game",
+        description: "Get which trophies a user has earned in a specific game, including earned " +
+            "timestamps and global rarity. Combine with psn_get_title_trophies for trophy " +
+            "names and descriptions (this endpoint returns ids and earned state).",
+        inputSchema: {
+            user: userParam.default("me"),
+            npCommunicationId: z
+                .string()
+                .describe('Trophy set id, e.g. "NPWR20188_00".'),
+            npServiceName: npServiceNameParam,
+            trophyGroupId: z.string().default("all"),
+            limit: z.number().int().min(1).max(500).default(200),
+            offset: z.number().int().min(0).default(0),
+        },
+    }, handle(async ({ user, npCommunicationId, npServiceName, trophyGroupId, limit, offset }) => psn.getEarnedTrophies(await psn.resolveAccountId(user), npCommunicationId, npServiceName, trophyGroupId, limit, offset)));
+    server.registerTool("psn_get_played_games", {
+        title: "Get played games",
+        description: "List the PS4/PS5 games a user has played, with play counts, first/last " +
+            "played dates, and total play duration. Subject to the user's privacy settings.",
+        inputSchema: {
+            user: userParam.default("me"),
+            limit: z.number().int().min(1).max(200).default(50).describe("Max games to return."),
+            offset: z.number().int().min(0).default(0).describe("Pagination offset."),
+        },
+    }, handle(async ({ user, limit, offset }) => psn.getPlayedGames(await psn.resolveAccountId(user), limit, offset)));
+}
+//# sourceMappingURL=tools.js.map

package/dist/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "psn-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for interfacing with the PlayStation Network",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "psn-mcp": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "playstation",
+    "psn",
+    "trophies"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.7.0"
+  }
+}