feat: add pcm_get_team_roster tool

AGENTS.md

@@ -27,15 +27,18 @@ read-only guarantee.
 src/
   index.ts        # entrypoint: builds McpServer, registers tools, connects stdio
   saves.ts        # save discovery + validation (listSaves, validateSave, getPcmRoot)
-  save-db.ts      # withSaveDb(): open .cdb in-memory, run fn, always close db
-  helpers.ts      # validResponse / errorResponse → CallToolResult
+  save-db.ts      # withSaveDb(): open .cdb in-memory, run fn, always close db; getGameDate()
+  helpers.ts      # validResponse / errorResponse → CallToolResult; ageFromYmd()
+  schemas/
+    cyclist.ts          # shared cyclist ratings: ratingsSchema / ratingsColumns() / mapRatings()
   tools/
     index.ts              # registerTools() — wires every tool onto the server
     list-saves.ts         # pcm_list_saves
     select-save.ts        # pcm_select_save
     get-save-schema.ts    # pcm_get_save_schema
     get-table-schema.ts   # pcm_get_table_schema
     get-player-info.ts    # pcm_get_player_info
+    get-team-roster.ts    # pcm_get_team_roster
     search-cyclist.ts     # pcm_search_cyclist
     search-team.ts        # pcm_search_team
     query-save.ts         # pcm_query_save
@@ -53,6 +56,7 @@ All tools are prefixed with `pcm_` and carry `readOnlyHint: true` / `destructive
 | `pcm_get_save_schema`  | List all tables (id + name) in a save via `DB_STRUCTURE`.                                                              |
 | `pcm_get_table_schema` | Inspect one table: columns (name, type, NOT NULL, PK) + row count.                                                     |
 | `pcm_get_player_info`  | Active human player + team (joins `GAM_user` `game_i_active = 1` with `DYN_team`).                                     |
+| `pcm_get_team_roster`  | Team roster (defaults to active player's team). Joins `DYN_cyclist` with active `DYN_contract_cyclist` + `STA_type_rider`: name, country, age, type, overall, contract end, wage, value, plus per-terrain ratings (flat). Errors on unknown `teamId`. |
 | `pcm_search_cyclist`   | Search cyclist by first/last name (partial, case-insensitive).                                                         |
 | `pcm_search_team`      | Search team by name (partial, case-insensitive; matches full name and short name).                                    |
 | `pcm_query_save`       | Run a single read-only `SELECT`/`WITH … SELECT`. Write/DDL rejected; results capped (default 100, max 1000).           |

README.md

@@ -75,16 +75,17 @@ Auto-discovery via `pcm_list_saves` is therefore **Windows only**. On macOS/Linu
 
 All tools are read-only and carry `readOnlyHint: true`, so clients like Claude Desktop can approve them automatically without a confirmation prompt.
 
-| Tool                     | Description                                                                                                                                                                                                                                  |
-| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **pcm_list_saves**       | Discover PCM `.cdb` career save files on this machine by scanning the `Pro Cycling Manager <year>/Cloud` folders under `%APPDATA%` (Windows only). Returns each save's absolute path, file name, last modified date and size (newest first). |
-| **pcm_select_save**      | Validate that an absolute path points to an existing `.cdb` save file and return its metadata. Stateless — keep the returned path in conversation context to pass to later tools.                                                            |
-| **pcm_get_save_schema**  | List every table inside a `.cdb` save file, with its ID and name, plus the total table count.                                                                                                                                                |
-| **pcm_get_table_schema** | Inspect a single table by name. Returns its columns (name, SQL type, NOT NULL and primary key flags) and its row count. Use `pcm_get_save_schema` first to discover available table names.                                                   |
-| **pcm_get_player_info**  | Get the active human player and their team from a save file. Returns the player login plus team details (name, resolved division name, resolved country name, evaluation and manager).                                                       |
-| **pcm_search_cyclist**   | Search for a cyclist by first name and/or last name (case-insensitive partial match). Returns up to 10 matches with all ratings (plain, mountain, medium mountain, downhilling, cobble, time trial, prologue, sprint, acceleration, endurance, resistance, recuperation, hill, baroudeur, current ability) and the resolved country name. `mediumMountain` and `currentAbility` are `null` on saves that pre-date those columns. |
-| **pcm_search_team**      | Search for a team by name (case-insensitive partial match against both the full name and short name). Returns up to 10 matches with the resolved division name, country name, evaluation and general manager. |
-| **pcm_query_save**       | Run a read-only SQL query (`SELECT` / `WITH … SELECT` only) against any table in a save file. Write/DDL statements are rejected. Results are capped (default 100, max 1000 rows).                                                            |
+| Tool                     | Description                                                                                                                                                                                                                                                                                                                                                                                                                                      |
+| ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| **pcm_list_saves**       | Discover PCM `.cdb` career save files on this machine by scanning the `Pro Cycling Manager <year>/Cloud` folders under `%APPDATA%` (Windows only). Returns each save's absolute path, file name, last modified date and size (newest first).                                                                                                                                                                                                     |
+| **pcm_select_save**      | Validate that an absolute path points to an existing `.cdb` save file and return its metadata. Stateless — keep the returned path in conversation context to pass to later tools.                                                                                                                                                                                                                                                                |
+| **pcm_get_save_schema**  | List every table inside a `.cdb` save file, with its ID and name, plus the total table count.                                                                                                                                                                                                                                                                                                                                                    |
+| **pcm_get_table_schema** | Inspect a single table by name. Returns its columns (name, SQL type, NOT NULL and primary key flags) and its row count. Use `pcm_get_save_schema` first to discover available table names.                                                                                                                                                                                                                                                       |
+| **pcm_get_player_info**  | Get the active human player and their team from a save file. Returns the player login plus team details (name, resolved division name, resolved country name, evaluation and manager).                                                                                                                                                                                                                                                           |
+| **pcm_search_cyclist**   | Search for a cyclist by first name and/or last name (case-insensitive partial match). Returns up to 10 matches with all ratings (plain, mountain, medium mountain, downhilling, cobble, time trial, prologue, sprint, acceleration, endurance, resistance, recuperation, hill, baroudeur, current ability) and the resolved country name. `mediumMountain` and `currentAbility` are `null` on saves that pre-date those columns.                 |
+| **pcm_get_team_roster**  | List a team's roster (defaults to the active player's team when `teamId` is omitted). Joins DYN_cyclist with its active DYN_contract_cyclist and STA_type_rider; per rider returns name, country, age (derived from birth date and the current game date), rider type, overall ability, contract end year, wage, market value and all per-terrain ability ratings. Ordered by overall ability, highest first. Errors if `teamId` does not exist. |
+| **pcm_search_team**      | Search for a team by name (case-insensitive partial match against both the full name and short name). Returns up to 10 matches with the resolved division name, country name, evaluation and general manager.                                                                                                                                                                                                                                    |
+| **pcm_query_save**       | Run a read-only SQL query (`SELECT` / `WITH … SELECT` only) against any table in a save file. Write/DDL statements are rejected. Results are capped (default 100, max 1000 rows).                                                                                                                                                                                                                                                                |
 
 ## Development
 

src/helpers.ts

@@ -29,3 +29,13 @@ export function errorResponse(error: string): CallToolResult {
 		isError: true,
 	};
 }
+
+/** Compute age in whole years from two YYYYMMDD integers (e.g. 20030503). */
+export function ageFromYmd(currentYmd: number, birthYmd: number): number {
+	let age = Math.floor(currentYmd / 10000) - Math.floor(birthYmd / 10000);
+	// Decrement if this year's birthday (MMDD) has not occurred yet.
+	if (currentYmd % 10000 < birthYmd % 10000) {
+		age--;
+	}
+	return age;
+}

src/save-db.ts

@@ -6,7 +6,25 @@ import { errorResponse, validResponse } from "./helpers";
 import { type SaveFile, validateSave } from "./saves";
 
 /** An in-memory sql.js database produced from a `.cdb` save by `cdbToSql`. */
-type SaveDb = ReturnType<typeof cdbToSql>;
+export type SaveDb = ReturnType<typeof cdbToSql>;
+
+/**
+ * Read the current in-game date from a save as a `YYYYMMDD` integer
+ * (e.g. `20260605`), or `null` when it can't be found.
+ *
+ * PCM stores the career's current date in `GAM_config.gene_i_date`. It is the
+ * reference point for any age- or season-relative computation, since the
+ * on-disk save advances as the career is played.
+ */
+export function getGameDate(db: SaveDb): number | null {
+	try {
+		const result = db.exec("SELECT gene_i_date FROM GAM_config LIMIT 1");
+		const raw = result[0]?.values?.[0]?.[0];
+		return raw != null ? Number(raw) : null;
+	} catch {
+		return null;
+	}
+}
 
 /**
  * Open a Pro Cycling Manager `.cdb` save as an in-memory SQL database, run

src/schemas/cyclist.ts

@@ -0,0 +1,79 @@
+import { z } from "zod";
+
+/**
+ * Per-terrain ability ratings shared by every tool that returns a cyclist
+ * (`pcm_search_cyclist`, `pcm_get_team_roster`). These map one-to-one to the
+ * `charac_i_*` columns on `DYN_cyclist`.
+ *
+ * Spread `ratingsSchema.shape` into a cyclist's output schema to keep the
+ * ratings flat, and use {@link mapRatings} to read them off a result row (both
+ * expect the columns to be aliased to the field names below).
+ */
+export const ratingsSchema = z.object({
+	plain: z.number().describe("Plain rating (charac_i_plain)"),
+	mountain: z.number().describe("Mountain rating (charac_i_mountain)"),
+	mediumMountain: z
+		.number()
+		.nullable()
+		.describe(
+			"Medium mountain rating (charac_i_medium_mountain) — null on saves that pre-date this column",
+		),
+	downhilling: z.number().describe("Downhilling rating (charac_i_downhilling)"),
+	cobble: z.number().describe("Cobblestone rating (charac_i_cobble)"),
+	timeTrial: z.number().describe("Time trial rating (charac_i_timetrial)"),
+	prologue: z.number().describe("Prologue rating (charac_i_prologue)"),
+	sprint: z.number().describe("Sprint rating (charac_i_sprint)"),
+	acceleration: z
+		.number()
+		.describe("Acceleration rating (charac_i_acceleration)"),
+	endurance: z.number().describe("Endurance rating (charac_i_endurance)"),
+	resistance: z.number().describe("Resistance rating (charac_i_resistance)"),
+	recuperation: z
+		.number()
+		.describe("Recuperation rating (charac_i_recuperation)"),
+	hill: z.number().describe("Hill rating (charac_i_hill)"),
+	baroudeur: z.number().describe("Baroudeur rating (charac_i_baroudeur)"),
+});
+
+/** SQL `SELECT` fragment that aliases the rating columns to {@link ratingsSchema}'s
+ * field names. `mediumMountain` falls back to `NULL` on saves that pre-date the
+ * `charac_i_medium_mountain` column. */
+export function ratingsColumns(hasMediumMountain: boolean): string {
+	return `c.charac_i_plain           AS plain,
+			c.charac_i_mountain        AS mountain,
+			${hasMediumMountain ? "c.charac_i_medium_mountain" : "NULL"} AS mediumMountain,
+			c.charac_i_downhilling     AS downhilling,
+			c.charac_i_cobble          AS cobble,
+			c.charac_i_timetrial       AS timeTrial,
+			c.charac_i_prologue        AS prologue,
+			c.charac_i_sprint          AS sprint,
+			c.charac_i_acceleration    AS acceleration,
+			c.charac_i_endurance       AS endurance,
+			c.charac_i_resistance      AS resistance,
+			c.charac_i_recuperation    AS recuperation,
+			c.charac_i_hill            AS hill,
+			c.charac_i_baroudeur       AS baroudeur`;
+}
+
+/** Read the rating fields off a query row aliased per {@link ratingsColumns}. */
+export function mapRatings(
+	row: Record<string, unknown>,
+): z.infer<typeof ratingsSchema> {
+	return {
+		plain: Number(row.plain),
+		mountain: Number(row.mountain),
+		mediumMountain:
+			row.mediumMountain != null ? Number(row.mediumMountain) : null,
+		downhilling: Number(row.downhilling),
+		cobble: Number(row.cobble),
+		timeTrial: Number(row.timeTrial),
+		prologue: Number(row.prologue),
+		sprint: Number(row.sprint),
+		acceleration: Number(row.acceleration),
+		endurance: Number(row.endurance),
+		resistance: Number(row.resistance),
+		recuperation: Number(row.recuperation),
+		hill: Number(row.hill),
+		baroudeur: Number(row.baroudeur),
+	};
+}