From fb7af7b28165ab6710372d1a1bd0236ed11bfbd6 Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Mon, 29 Jun 2026 08:32:22 -0400 Subject: [PATCH 1/3] feat: add pcm_generate_startlist_xml tool Add a tool that builds a Pro Cycling Manager startlist XML document from a list of teams and their cyclist rosters. The output file name is derived from STA_race.gene_sz_filename for the given IDrace (e.g. c0_almeria.xml), so the tool reads the .cdb save via withSaveDb to resolve it. The XML builder lives in helpers.ts (buildStartlistXml) and is covered by unit tests. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 4 +- README.md | 1 + src/helpers.ts | 30 ++++++++++ src/tools/generate-startlist-xml.ts | 93 +++++++++++++++++++++++++++++ src/tools/index.ts | 2 + test/generate-startlist-xml.test.ts | 76 +++++++++++++++++++++++ 6 files changed, 205 insertions(+), 1 deletion(-) create mode 100644 src/tools/generate-startlist-xml.ts create mode 100644 test/generate-startlist-xml.test.ts diff --git a/AGENTS.md b/AGENTS.md index ed138c4..8a0811b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,7 +28,7 @@ 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 + helpers.ts # validResponse / errorResponse → CallToolResult; buildStartlistXml tools/ index.ts # registerTools() — wires every tool onto the server list-saves.ts # pcm_list_saves @@ -38,6 +38,7 @@ src/ get-player-info.ts # pcm_get_player_info search-cyclist.ts # pcm_search_cyclist query-save.ts # pcm_query_save + generate-startlist-xml.ts # pcm_generate_startlist_xml test/ # vitest specs (test/**/*.test.ts) ``` @@ -54,6 +55,7 @@ All tools are prefixed with `pcm_` and carry `readOnlyHint: true` / `destructive | `pcm_get_player_info` | Active human player + team (joins `GAM_user` `game_i_active = 1` with `DYN_team`). | | `pcm_search_cyclist` | Search cyclist by first/last name (partial, case-insensitive). | | `pcm_query_save` | Run a single read-only `SELECT`/`WITH … SELECT`. Write/DDL rejected; results capped (default 100, max 1000). | +| `pcm_generate_startlist_xml` | Build a PCM startlist XML from teams + rosters; derives the file name from `STA_race.gene_sz_filename` for the given `IDrace`. | ## Conventions diff --git a/README.md b/README.md index 171a073..028685d 100644 --- a/README.md +++ b/README.md @@ -84,6 +84,7 @@ All tools are read-only and carry `readOnlyHint: true`, so clients like Claude D | **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_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). | +| **pcm_generate_startlist_xml** | Generate a PCM startlist XML document from a list of teams and their cyclist rosters. Looks up the race by `IDrace` in the save to derive the output file name from `STA_race.gene_sz_filename` (e.g. `c0_almeria.xml`), and returns both the file name and the XML as text. Team and cyclist IDs map to `DYN_team.IDteam` / `DYN_cyclist.IDcyclist` (look them up with `pcm_search_cyclist` or `pcm_query_save`). | ## Development diff --git a/src/helpers.ts b/src/helpers.ts index 14197f5..cc082b4 100644 --- a/src/helpers.ts +++ b/src/helpers.ts @@ -29,3 +29,33 @@ export function errorResponse(error: string): CallToolResult { isError: true, }; } + +export interface StartlistTeam { + id: number; + cyclists: number[]; +} + +/** + * Build a Pro Cycling Manager startlist XML document from a list of teams and + * their cyclist rosters. The output mirrors PCM's expected format: a + * `` root, `` children (4-space indent) and + * self-closing `` elements (8-space indent). + */ +export function buildStartlistXml(teams: StartlistTeam[]): string { + if (teams.length === 0) { + throw new Error("Provide at least one team."); + } + const lines: string[] = [""]; + for (const team of teams) { + if (team.cyclists.length === 0) { + throw new Error(`Team ${team.id} has no cyclists.`); + } + lines.push(` `); + for (const cyclistId of team.cyclists) { + lines.push(` `); + } + lines.push(" "); + } + lines.push(""); + return `${lines.join("\n")}\n`; +} diff --git a/src/tools/generate-startlist-xml.ts b/src/tools/generate-startlist-xml.ts new file mode 100644 index 0000000..dd15b52 --- /dev/null +++ b/src/tools/generate-startlist-xml.ts @@ -0,0 +1,93 @@ +import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { z } from "zod"; +import { buildStartlistXml } from "../helpers"; +import { withSaveDb } from "../save-db"; + +/** + * Resolve the startlist file name for a race from its `STA_race` row. + * + * PCM stores the base name in `STA_race.gene_sz_filename` (e.g. `c0_almeria`); + * the startlist file is that base name with a `.xml` extension. + */ +export function resolveStartlistFileName(filenameBase: string): string { + return filenameBase.endsWith(".xml") ? filenameBase : `${filenameBase}.xml`; +} + +const outputSchema = z.object({ + fileName: z + .string() + .describe( + "Suggested file name for the startlist, derived from STA_race.gene_sz_filename (e.g. `c0_almeria.xml`)", + ), + xml: z.string().describe("Generated PCM startlist XML document"), +}); + +export function registerGenerateStartlistXml(server: McpServer): void { + server.registerTool( + "pcm_generate_startlist_xml", + { + title: "Generate PCM startlist XML", + description: + 'Generate a Pro Cycling Manager startlist XML document from a list of teams and their cyclist rosters. Looks up the race in the `.cdb` save by `IDrace` to derive the output file name from `STA_race.gene_sz_filename` (e.g. `c0_almeria.xml`). Returns both the file name and the XML as text. The XML is a `` root containing `` elements, each with self-closing `` children. Team and cyclist IDs map to the PCM `DYN_team.IDteam` and `DYN_cyclist.IDcyclist` columns and can be looked up with `pcm_search_cyclist` or `pcm_query_save`. The number of cyclists per team is free.', + inputSchema: { + savePath: z.string().describe("Absolute path to the .cdb save file"), + raceId: z + .number() + .int() + .describe( + "Race ID (STA_race.IDrace) used to derive the output file name", + ), + teams: z + .array( + z.object({ + id: z + .number() + .int() + .describe("Team ID (PCM DYN_team.IDteam / fkIDteam)"), + cyclists: z + .array(z.number().int()) + .describe( + "Cyclist IDs (DYN_cyclist.IDcyclist) for this team's roster", + ), + }), + ) + .describe( + "Teams entered in the race, each with its roster of cyclist IDs", + ), + }, + outputSchema, + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: false, + }, + }, + async ({ savePath, raceId, teams }) => + withSaveDb(savePath, (db) => { + const stmt = db.prepare( + "SELECT gene_sz_filename FROM STA_race WHERE IDrace = :raceId", + ); + let filenameBase: string; + try { + stmt.bind({ ":raceId": raceId }); + if (!stmt.step()) { + throw new Error(`No race found with IDrace ${raceId} in STA_race.`); + } + const value = stmt.getAsObject().gene_sz_filename; + if (value == null || String(value).length === 0) { + throw new Error(`Race ${raceId} has no gene_sz_filename.`); + } + filenameBase = String(value); + } finally { + stmt.free(); + } + + const output: z.infer = { + fileName: resolveStartlistFileName(filenameBase), + xml: buildStartlistXml(teams), + }; + return output; + }), + ); +} diff --git a/src/tools/index.ts b/src/tools/index.ts index f3a4fea..c6120ff 100644 --- a/src/tools/index.ts +++ b/src/tools/index.ts @@ -6,6 +6,7 @@ import { registerGetTableSchema } from "./get-table-schema"; import { registerGetPlayerInfo } from "./get-player-info"; import { registerQuerySave } from "./query-save"; import { registerSearchCyclist } from "./search-cyclist"; +import { registerGenerateStartlistXml } from "./generate-startlist-xml"; export function registerTools(server: McpServer): void { registerListSaves(server); @@ -15,4 +16,5 @@ export function registerTools(server: McpServer): void { registerGetPlayerInfo(server); registerQuerySave(server); registerSearchCyclist(server); + registerGenerateStartlistXml(server); } diff --git a/test/generate-startlist-xml.test.ts b/test/generate-startlist-xml.test.ts new file mode 100644 index 0000000..45c9bf4 --- /dev/null +++ b/test/generate-startlist-xml.test.ts @@ -0,0 +1,76 @@ +import { describe, expect, it } from "vitest"; +import { buildStartlistXml } from "../src/helpers"; +import { resolveStartlistFileName } from "../src/tools/generate-startlist-xml"; + +describe("buildStartlistXml", () => { + it("builds XML for a single team", () => { + const xml = buildStartlistXml([{ id: 34, cyclists: [7602, 5996] }]); + expect(xml).toBe( + [ + "", + ' ', + ' ', + ' ', + " ", + "", + "", + ].join("\n"), + ); + }); + + it("builds XML for multiple teams with variable roster sizes", () => { + const xml = buildStartlistXml([ + { id: 34, cyclists: [1, 2, 3, 4, 5, 6, 7] }, + { id: 81, cyclists: [10, 11, 12, 13, 14, 15] }, + ]); + expect(xml).toBe( + [ + "", + ' ', + ' ', + ' ', + ' ', + ' ', + ' ', + ' ', + ' ', + " ", + ' ', + ' ', + ' ', + ' ', + ' ', + ' ', + ' ', + " ", + "", + "", + ].join("\n"), + ); + }); + + it("ends the document with a trailing newline", () => { + const xml = buildStartlistXml([{ id: 1, cyclists: [1] }]); + expect(xml.endsWith("\n")).toBe(true); + }); + + it("throws when no team is provided", () => { + expect(() => buildStartlistXml([])).toThrow("Provide at least one team."); + }); + + it("throws when a team has no cyclists", () => { + expect(() => buildStartlistXml([{ id: 34, cyclists: [] }])).toThrow( + "Team 34 has no cyclists.", + ); + }); +}); + +describe("resolveStartlistFileName", () => { + it("appends .xml to the STA_race base name", () => { + expect(resolveStartlistFileName("c0_almeria")).toBe("c0_almeria.xml"); + }); + + it("does not double-append when .xml is already present", () => { + expect(resolveStartlistFileName("c0_almeria.xml")).toBe("c0_almeria.xml"); + }); +}); From 712861d4ebd5ac23b257b47801813b1d7e4e422c Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Mon, 29 Jun 2026 08:46:12 -0400 Subject: [PATCH 2/3] feat: add pcm-startlist skill Add a project skill that orchestrates the read-only PCM MCP tools to compose a race startlist (find the race, choose teams, pick riders per profile) and delegates serialization to the pcm_generate_startlist_xml tool. Co-Authored-By: Claude Opus 4.8 --- .claude/skills/pcm-startlist/SKILL.md | 109 ++++++++++++++++++++++++++ 1 file changed, 109 insertions(+) create mode 100644 .claude/skills/pcm-startlist/SKILL.md diff --git a/.claude/skills/pcm-startlist/SKILL.md b/.claude/skills/pcm-startlist/SKILL.md new file mode 100644 index 0000000..25fbf4d --- /dev/null +++ b/.claude/skills/pcm-startlist/SKILL.md @@ -0,0 +1,109 @@ +--- +name: pcm-startlist +description: >- + Build a Pro Cycling Manager (PCM) race startlist and export it as the .xml + file PCM imports. Use when the user wants to create, compose, or generate a + startlist for a PCM race — picking which teams take part and which riders + each team brings. Orchestrates the read-only PCM MCP tools (pcm_query_save, + pcm_search_cyclist) to gather data and pcm_generate_startlist_xml to produce + the file. Triggers on phrases like "startlist", "liste de départ", + "engagés pour la course", "génère le fichier xml de la course X". +--- + +# PCM startlist builder + +Compose a startlist for a Pro Cycling Manager race and write the `.xml` file PCM +imports. This skill owns the *workflow* (find the race, choose teams, choose +riders); the deterministic serialization is delegated to the +`pcm_generate_startlist_xml` MCP tool — never hand-write the XML. + +## Output format (for reference only — the tool emits this) + +```xml + + + + + + +``` + +`` = `DYN_team.IDteam`, `` = `DYN_cyclist.IDcyclist`. The file +name is `STA_race.gene_sz_filename` + `.xml` (e.g. `c0_almeria.xml`) and is +returned by the tool — don't invent it. + +## Workflow + +### 1. Get a save path +Every step reads a `.cdb` save. If the user hasn't given an absolute `savePath`: +- Try `pcm_list_saves` (Windows only — fails on macOS/Linux Wine/Proton prefixes). +- Otherwise ask the user for the absolute `.cdb` path. Keep it in context; the + tools are stateless and need it on every call. + +### 2. Identify the race (get `IDrace`) +The user names a race; resolve it to an `IDrace` with `pcm_query_save`: + +```sql +SELECT IDrace, gene_sz_race_name, gene_sz_filename +FROM STA_race +WHERE gene_sz_race_name LIKE '%almeria%'; +``` + +If several match, show the candidates (name + id) and let the user pick. Confirm +the `gene_sz_filename` so the user knows the output file name up front. + +### 3. Decide which teams take part +Either the user supplies the teams, or you propose them. Resolve names to +`IDteam`: + +```sql +SELECT IDteam, gene_sz_name, gene_sz_shortname FROM DYN_team +WHERE gene_sz_name LIKE '%ineos%'; +``` + +A typical startlist has ~18–25 teams. If the user just says "the usual teams", +ask which division/tier or list candidates rather than guessing. + +### 4. Pick riders per team +A team's full squad is the candidate pool — a startlist usually brings **7** of +them (the count is free; the example pack mixes 6 and 7). Get a team's roster: + +```sql +SELECT IDcyclist, gene_sz_firstname, gene_sz_lastname +FROM DYN_cyclist +WHERE fkIDteam = 34; +``` + +To pick riders that fit the race profile, pull the ratings too (the +`charac_i_*` columns — see `pcm_search_cyclist`, which already surfaces them) and +favour the relevant specialty: sprinters/`charac_i_sprint` for flat finishes, +`charac_i_mountain` for climbs, `charac_i_cobble` for cobbled classics, etc. If +the user has preferences (leaders, exclusions), apply them. Confirm the selection +before generating when there's any ambiguity. + +### 5. Generate the file +Call `pcm_generate_startlist_xml` with `savePath`, `raceId`, and `teams`: + +```json +{ + "savePath": "/abs/path/Career.cdb", + "raceId": 128, + "teams": [ + { "id": 34, "cyclists": [7602, 5996, 1381, 3291, 6342, 3912, 5613] }, + { "id": 25, "cyclists": [6346, 8702, 17152, 15300, 7048, 6433, 15398] } + ] +} +``` + +The tool returns `{ fileName, xml }`. If a team has no riders or `teams` is empty +the tool errors — fix the selection and retry. + +### 6. Deliver +Present the returned `fileName` and `xml`. Offer to write it to disk (e.g. the +user's PCM `Startlists`/race-import folder or the working directory) — the MCP +server is read-only and does not write files, so saving is done outside it. + +## Notes +- All PCM MCP tools are read-only; this workflow never modifies the save. +- IDs, not names, go into the XML — always resolve names to `IDteam`/`IDcyclist` + via the queries above before calling the tool. From d7cc67fa229a2f3b08ff2f468c9a26959950faa6 Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Mon, 29 Jun 2026 09:02:55 -0400 Subject: [PATCH 3/3] refactor: move and restore resolveStartlistFileName function --- src/tools/generate-startlist-xml.ts | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/src/tools/generate-startlist-xml.ts b/src/tools/generate-startlist-xml.ts index dd15b52..ab1834b 100644 --- a/src/tools/generate-startlist-xml.ts +++ b/src/tools/generate-startlist-xml.ts @@ -3,16 +3,6 @@ import { z } from "zod"; import { buildStartlistXml } from "../helpers"; import { withSaveDb } from "../save-db"; -/** - * Resolve the startlist file name for a race from its `STA_race` row. - * - * PCM stores the base name in `STA_race.gene_sz_filename` (e.g. `c0_almeria`); - * the startlist file is that base name with a `.xml` extension. - */ -export function resolveStartlistFileName(filenameBase: string): string { - return filenameBase.endsWith(".xml") ? filenameBase : `${filenameBase}.xml`; -} - const outputSchema = z.object({ fileName: z .string() @@ -91,3 +81,13 @@ export function registerGenerateStartlistXml(server: McpServer): void { }), ); } + +/** + * Resolve the startlist file name for a race from its `STA_race` row. + * + * PCM stores the base name in `STA_race.gene_sz_filename` (e.g. `c0_almeria`); + * the startlist file is that base name with a `.xml` extension. + */ +export function resolveStartlistFileName(filenameBase: string): string { + return filenameBase.endsWith(".xml") ? filenameBase : `${filenameBase}.xml`; +}