From cc972c31563358e4ed42e5047bad437b1251d352 Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Sat, 27 Jun 2026 10:20:03 -0400 Subject: [PATCH 1/5] feat: add search cyclist tool functionality --- src/tools/index.ts | 2 + src/tools/search-cyclist.ts | 134 ++++++++++++++++++++++++++++++++++++ 2 files changed, 136 insertions(+) create mode 100644 src/tools/search-cyclist.ts diff --git a/src/tools/index.ts b/src/tools/index.ts index ad82088..f3a4fea 100644 --- a/src/tools/index.ts +++ b/src/tools/index.ts @@ -5,6 +5,7 @@ import { registerGetSaveSchema } from "./get-save-schema"; import { registerGetTableSchema } from "./get-table-schema"; import { registerGetPlayerInfo } from "./get-player-info"; import { registerQuerySave } from "./query-save"; +import { registerSearchCyclist } from "./search-cyclist"; export function registerTools(server: McpServer): void { registerListSaves(server); @@ -13,4 +14,5 @@ export function registerTools(server: McpServer): void { registerGetTableSchema(server); registerGetPlayerInfo(server); registerQuerySave(server); + registerSearchCyclist(server); } diff --git a/src/tools/search-cyclist.ts b/src/tools/search-cyclist.ts new file mode 100644 index 0000000..30e48ef --- /dev/null +++ b/src/tools/search-cyclist.ts @@ -0,0 +1,134 @@ +import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"; +import { z } from "zod"; +import { withSaveDb } from "../save-db"; + +const cyclistSchema = z.object({ + id: z.number().describe("Cyclist ID (IDcyclist)"), + firstName: z.string().describe("First name (gene_sz_firstname)"), + lastName: z.string().describe("Last name (gene_sz_lastname)"), + country: z.string().nullable().describe("Country name (STA_country.CONSTANT)"), + 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)"), + currentAbility: z.number().nullable().describe("Current ability (value_f_current_ability) — null on saves that pre-date this column"), +}); + +const outputSchema = z.object({ + cyclists: z.array(cyclistSchema).describe("Matching cyclists"), + resultCount: z.number().describe("Number of results returned (max 10)"), +}); + +export function registerSearchCyclist(server: McpServer): void { + server.registerTool( + "pcm_search_cyclist", + { + title: "Search PCM cyclist by name", + description: + "Search for a cyclist in a Pro Cycling Manager `.cdb` save file by first name and/or last name (case-insensitive partial match). Returns up to 10 matching cyclists with all their ratings and their country name.", + inputSchema: { + savePath: z.string().describe("Absolute path to the .cdb save file"), + firstName: z + .string() + .optional() + .describe("First name to search for (partial match, case-insensitive)"), + lastName: z + .string() + .optional() + .describe("Last name to search for (partial match, case-insensitive)"), + }, + outputSchema, + annotations: { + readOnlyHint: true, + destructiveHint: false, + idempotentHint: true, + openWorldHint: false, + }, + }, + async ({ savePath, firstName = "", lastName = "" }) => + withSaveDb(savePath, (db) => { + const columnInfo = db.exec(`PRAGMA table_info("DYN_cyclist")`); + const columnNames = new Set( + (columnInfo[0]?.values ?? []).map((r) => String(r[1])), + ); + const hasMediumMountain = columnNames.has("charac_i_medium_mountain"); + const hasCurrentAbility = columnNames.has("value_f_current_ability"); + + const stmt = db.prepare( + `SELECT + c.IDcyclist, + c.gene_sz_firstname, + c.gene_sz_lastname, + 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, + ${hasCurrentAbility ? "c.value_f_current_ability" : "NULL"} AS currentAbility, + co.CONSTANT AS country + FROM DYN_cyclist c + LEFT JOIN STA_region r ON c.fkIDregion = r.IDregion + LEFT JOIN STA_country co ON r.fkIDcountry = co.IDcountry + WHERE LOWER(c.gene_sz_lastname) LIKE LOWER(:lastName) + AND LOWER(c.gene_sz_firstname) LIKE LOWER(:firstName) + LIMIT 10`, + ); + + const cyclists: z.infer[] = []; + try { + stmt.bind({ + ":lastName": `%${lastName}%`, + ":firstName": `%${firstName}%`, + }); + + while (stmt.step()) { + const row = stmt.getAsObject(); + cyclists.push({ + id: Number(row.IDcyclist), + firstName: String(row.gene_sz_firstname), + lastName: String(row.gene_sz_lastname), + country: row.country != null ? String(row.country) : null, + 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), + currentAbility: row.currentAbility != null ? Number(row.currentAbility) : null, + }); + } + } finally { + stmt.free(); + } + + return { cyclists, resultCount: cyclists.length }; + }), + ); +} From 053637562015d9e0970bcd01f0dad102e2d93f1d Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Sat, 27 Jun 2026 10:20:03 -0400 Subject: [PATCH 2/5] feat: add search cyclist tool to documentation --- AGENTS.md | 2 ++ README.md | 1 + 2 files changed, 3 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 12f2ab2..ed138c4 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -36,6 +36,7 @@ src/ get-save-schema.ts # pcm_get_save_schema get-table-schema.ts # pcm_get_table_schema get-player-info.ts # pcm_get_player_info + search-cyclist.ts # pcm_search_cyclist query-save.ts # pcm_query_save test/ # vitest specs (test/**/*.test.ts) ``` @@ -51,6 +52,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_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). | ## Conventions diff --git a/README.md b/README.md index b769b4b..171a073 100644 --- a/README.md +++ b/README.md @@ -82,6 +82,7 @@ All tools are read-only and carry `readOnlyHint: true`, so clients like Claude D | **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_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 From 89391690ffc4ce68619398752c7446fca2cea4b7 Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Sat, 27 Jun 2026 10:20:29 -0400 Subject: [PATCH 3/5] style: improve formatting and readability of cyclist schema and search function --- src/tools/search-cyclist.ts | 41 +++++++++++++++++++++++++++++-------- 1 file changed, 32 insertions(+), 9 deletions(-) diff --git a/src/tools/search-cyclist.ts b/src/tools/search-cyclist.ts index 30e48ef..22adea5 100644 --- a/src/tools/search-cyclist.ts +++ b/src/tools/search-cyclist.ts @@ -6,22 +6,39 @@ const cyclistSchema = z.object({ id: z.number().describe("Cyclist ID (IDcyclist)"), firstName: z.string().describe("First name (gene_sz_firstname)"), lastName: z.string().describe("Last name (gene_sz_lastname)"), - country: z.string().nullable().describe("Country name (STA_country.CONSTANT)"), + country: z + .string() + .nullable() + .describe("Country name (STA_country.CONSTANT)"), 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"), + 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)"), + 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)"), + 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)"), - currentAbility: z.number().nullable().describe("Current ability (value_f_current_ability) — null on saves that pre-date this column"), + currentAbility: z + .number() + .nullable() + .describe( + "Current ability (value_f_current_ability) — null on saves that pre-date this column", + ), }); const outputSchema = z.object({ @@ -41,11 +58,15 @@ export function registerSearchCyclist(server: McpServer): void { firstName: z .string() .optional() - .describe("First name to search for (partial match, case-insensitive)"), + .describe( + "First name to search for (partial match, case-insensitive)", + ), lastName: z .string() .optional() - .describe("Last name to search for (partial match, case-insensitive)"), + .describe( + "Last name to search for (partial match, case-insensitive)", + ), }, outputSchema, annotations: { @@ -109,7 +130,8 @@ export function registerSearchCyclist(server: McpServer): void { country: row.country != null ? String(row.country) : null, plain: Number(row.plain), mountain: Number(row.mountain), - mediumMountain: row.mediumMountain != null ? Number(row.mediumMountain) : null, + mediumMountain: + row.mediumMountain != null ? Number(row.mediumMountain) : null, downhilling: Number(row.downhilling), cobble: Number(row.cobble), timeTrial: Number(row.timeTrial), @@ -121,7 +143,8 @@ export function registerSearchCyclist(server: McpServer): void { recuperation: Number(row.recuperation), hill: Number(row.hill), baroudeur: Number(row.baroudeur), - currentAbility: row.currentAbility != null ? Number(row.currentAbility) : null, + currentAbility: + row.currentAbility != null ? Number(row.currentAbility) : null, }); } } finally { From 9cd371bf7974239cc7833a8233fcc90a8f605f9c Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Sat, 27 Jun 2026 10:25:43 -0400 Subject: [PATCH 4/5] Trim inputs and rejecting calls where both are empty Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- src/tools/search-cyclist.ts | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/src/tools/search-cyclist.ts b/src/tools/search-cyclist.ts index 22adea5..dc03c02 100644 --- a/src/tools/search-cyclist.ts +++ b/src/tools/search-cyclist.ts @@ -116,9 +116,15 @@ export function registerSearchCyclist(server: McpServer): void { const cyclists: z.infer[] = []; try { + const first = firstName.trim(); + const last = lastName.trim(); + if (first.length === 0 && last.length === 0) { + throw new Error("Provide at least one of firstName or lastName."); + } + stmt.bind({ - ":lastName": `%${lastName}%`, - ":firstName": `%${firstName}%`, + ":lastName": `%${last}%`, + ":firstName": `%${first}%`, }); while (stmt.step()) { From 5246872406b3f5941f62cf4515fddfd15b3c17b3 Mon Sep 17 00:00:00 2001 From: Mathieu Picciolli Date: Sat, 27 Jun 2026 10:26:24 -0400 Subject: [PATCH 5/5] refactor: remove resultCount from outputSchema and adjust return structure in registerSearchCyclist --- src/tools/search-cyclist.ts | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/src/tools/search-cyclist.ts b/src/tools/search-cyclist.ts index dc03c02..f44b36e 100644 --- a/src/tools/search-cyclist.ts +++ b/src/tools/search-cyclist.ts @@ -43,7 +43,6 @@ const cyclistSchema = z.object({ const outputSchema = z.object({ cyclists: z.array(cyclistSchema).describe("Matching cyclists"), - resultCount: z.number().describe("Number of results returned (max 10)"), }); export function registerSearchCyclist(server: McpServer): void { @@ -157,7 +156,10 @@ export function registerSearchCyclist(server: McpServer): void { stmt.free(); } - return { cyclists, resultCount: cyclists.length }; + const output: z.infer = { + cyclists, + }; + return output; }), ); }