refactor: name a .cdb a database, and keep "save" for the player's saves

[mpicciolli]

Summary

A .cdb file is a database — Cyanide's own binary format. It may be a career save, but equally an official release or a community update, and the tools never cared which. Calling every .cdb a "save" was therefore wrong for most inputs: every test fixture in this repo is an OfficialRelease-*.cdb, not a save.

This PR splits the two concepts and names them separately:

• database — any .cdb file. What every tool but one actually operates on.
• save — a .cdb the game itself wrote as the player played a career, found under a PCM edition's Cloud/ folder. Confined to src/saves.ts and pcm_list_saves.

The word "save" also doubled as a verb (writeSaveDb, pcm_update_save — "update the save" or "save the update"?), which this removes.

Breaking changes

Tool and parameter renames. MCP clients read the tool list at connect time, so no client configuration change is needed — only hand-written prompts, scripts or skills that name a tool or savePath explicitly.

Before	After
savePath (11 tools)	databasePath
pcm_validate_save	pcm_validate_database
pcm_get_save_schema	pcm_list_tables
pcm_query_save	pcm_query_database
pcm_update_save	pcm_update_database

pcm_list_saves keeps its name — it is the one tool genuinely about the player's saves. The seven other tools are unchanged apart from their databasePath parameter.

pcm_get_save_schema becomes pcm_list_tables rather than pcm_get_database_schema: it returns the table list, and the old name was asymmetric with pcm_get_table_schema (which returns columns).

No version bump — the release number is left to a separate decision.

Internal changes

• src/save-db.ts → src/cdb.ts, now owning everything that touches a .cdb: CdbFile, validateCdb, CdbDatabase, withCdb, writeCdb, getGameDate, getTableColumnNames.
• src/saves.ts is reduced to what its name claims: locating the player's career saves across installed PCM editions. validateSave lived here while validating arbitrary .cdb paths — the root of the ambiguity — and moved to cdb.ts as validateCdb, with its tests.
• Tool modules renamed to match their tools (get-save-schema.ts → list-tables.ts, etc.).
• test/fixtures/save.fixture.ts → database.fixture.ts, since those fixtures are official releases.
• Vocabulary unified: cyclist everywhere in tool descriptions (rider kept only for rider type / STA_type_rider), and Not a .cdb file replaces the misleading Not a .cdb save file error.

Documentation

• README.md — a "Saves and databases" section stating the distinction, plus a rename table for anyone with hand-written prompts.
• AGENTS.md — a Terminology section so the distinction holds for future changes.
• .claude/skills/pcm-startlist/SKILL.md updated to the new tool names.

[Copilot]

Pull request overview

This PR updates README terminology to consistently refer to PCM .cdb files as “saves” (instead of “career saves”), aligning the documentation with how the server and tools operate.

Changes:

• Updates the README intro copy to say “saves”.
• Rewords the “IMPORTANT” section to describe .cdb files as saves.
• Updates feature, prerequisites, platform support, and tool table wording to use “save”.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 39 out of 39 changed files in this pull request and generated no new comments.

Suppressed comments (3)

README.md:121

• The PR metadata says this is a docs-only terminology tweak, but the changes here document (and the PR implements) a breaking public API rename (tool names + savePath→databasePath). Please update the PR title/description (or split into separate PRs) so reviewers and release notes accurately reflect the scope.

## Renamed tools

Several tools and the parameter they all take were renamed, so that "save" now means only what the game itself saved and everything else says "database". MCP clients read the tool list at connect time, so **no configuration change is needed** — restart your client and it picks up the new names. Only hand-written prompts, scripts or skills that name a tool or `savePath` explicitly need updating:

package.json:4

• This PR renames multiple public MCP tools/parameters (breaking change). The package version is unchanged (still 0.3.0), which makes it hard for users to discover the breaking API change and for downstream clients to pin compatible versions. Consider bumping the package/manifest version as part of this change.

	"name": "pcm-mcp",
	"version": "0.3.0",
	"description": "MCP server for querying Pro Cycling Manager databases",

src/index.ts:16

• The MCP server description now says it only supports reading/validating, but this server also registers write tools (e.g. pcm_update_database, pcm_update_cyclist_ratings). This metadata can be surfaced by clients, so it should reflect the full capability set.

const server = new McpServer({
	name: "pcm-mcp",
	version,
	description:
		"Pro Cycling Manager MCP server for reading and validating .cdb database files",
});

[Copilot]

Pull request overview

Copilot reviewed 40 out of 40 changed files in this pull request and generated no new comments.

Suppressed comments (2)

src/index.ts:16

• The server description says it is for "reading and validating" .cdb files, but this server also exposes write tools (e.g. pcm_update_database, pcm_update_cyclist_ratings). This string is likely user-facing in MCP clients, so it should reflect editing capabilities too.

const server = new McpServer({
	name: "pcm-mcp",
	version,
	description:
		"Pro Cycling Manager MCP server for reading and validating .cdb database files",
});

manifest.json:6

• long_description contains a sentence fragment: "PCM stores its data as binary .cdb database files. Your career saves, but also the official releases and community updates." This reads ungrammatically in marketplace/client UIs; rephrase to a complete sentence.

	"long_description": "MCP server for querying and editing Pro Cycling Manager game databases. PCM stores its data as binary .cdb database files. Your career saves, but also the official releases and community updates. This server discovers your saves, and inspects and queries any .cdb via the MCP protocol, so AI assistants can explore it in a structured way. Write tools never modify the source: edits are always serialized to a new .cdb file, and existing files are never overwritten.",