Skip to content

docs: overhaul README with badges, features and how-it-works sections #11

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mpicciolli merged 1 commit into from
Jul 1, 2026
Merged

docs: overhaul README with badges, features and how-it-works sections #11

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 71 additions & 65 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,53 +2,56 @@
<img src="assets/icon.png" alt="PCM MCP" width="150" />
</p>

# Pro Cycling Manager MCP Server
<h1 align="center">Pro Cycling Manager MCP Server</h1>

A Model Context Protocol (MCP) server for querying Pro Cycling Manager (PCM) game databases. This server provides tools to discover and inspect PCM career save files via the MCP protocol, allowing AI assistants to explore your saves in a structured way.
<p align="center">
Explore your <strong>Pro Cycling Manager</strong> career saves with an AI assistant — riders, teams, rosters and startlists, straight from the game's database.
</p>

This server is strictly **read-only**. PCM stores careers as binary `.cdb` files; this server discovers and inspects those saves but **never writes to or modifies them**. Save files are loaded into an in-memory SQLite database for querying, and changes are never written back to disk.
<p align="center">
<a href="https://www.npmjs.com/package/pcm-mcp"><img src="https://img.shields.io/npm/v/pcm-mcp.svg" alt="npm version" /></a>
<a href="https://github.com/mpicciolli/pcm-mcp/blob/main/LICENSE"><img src="https://img.shields.io/npm/l/pcm-mcp.svg" alt="license" /></a>
<a href="https://nodejs.org"><img src="https://img.shields.io/node/v/pcm-mcp.svg" alt="node version" /></a>
<a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-blue.svg" alt="MCP compatible" /></a>
</p>

## Installation
`pcm-mcp` is a [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI assistants such as Claude Desktop, ChatGPT and Gemini query your [Pro Cycling Manager](https://www.cyanide-studio.com/) (PCM) game saves. Ask about a rider's ratings, browse a team's roster, run SQL against the save, or generate a race startlist — all in plain language.

### MCP Bundle
> [!IMPORTANT]
> This server is strictly **read-only**. PCM stores careers as binary `.cdb` files; each call re-reads the `.cdb` from disk and loads it into an **in-memory** SQLite database. Your save files are **never written to or modified**.

Download the latest `pcm-mcp.mcpb` from the [Releases page](https://github.com/mpicciolli/pcm-mcp/releases) and open it with **Claude for macOS or Windows**. An installation dialog will appear — no terminal required.
## Features

> **Note:** This method does not auto-update. To get a newer version, download and re-install the latest `.mcpb` from the Releases page.
- **Zero setup** — run it with a single `npx` command, or install a `.mcpb` bundle with no terminal at all.
- **Save discovery** — auto-detect PCM career saves on Windows, or point at any `.cdb` file directly.
- **Rich queries** — search cyclists and teams, inspect rosters with full per-terrain ratings, and read player info.
- **Raw SQL** — run guarded, read-only `SELECT` queries against any table in the save.
- **Startlist export** — generate a PCM-ready startlist XML from a set of teams and rosters.
- **Safe by design** — every tool is annotated `readOnlyHint: true`, so clients can auto-approve them without prompts.

### Claude Desktop
## Getting started

Add the following to your `claude_desktop_config.json`:
### Prerequisites

```json
{
"mcpServers": {
"pcm-mcp": {
"command": "npx",
"args": ["-y", "pcm-mcp"]
}
}
}
```
- [Node.js](https://nodejs.org) 22 or later (not required for the `.mcpb` bundle install)
- A Pro Cycling Manager career save (a `.cdb` file)

### ChatGPT Desktop
### Install

Add the following to your ChatGPT MCP configuration file:
<details open>
<summary><strong>MCP Bundle (Claude Desktop, no terminal)</strong></summary>

```json
{
"mcpServers": {
"pcm-mcp": {
"command": "npx",
"args": ["-y", "pcm-mcp"]
}
}
}
```
Download the latest `pcm-mcp.mcpb` from the [Releases page](https://github.com/mpicciolli/pcm-mcp/releases) and open it with **Claude for macOS or Windows**. An installation dialog appears — no terminal required.

> [!NOTE]
> This method does not auto-update. To get a newer version, download and re-install the latest `.mcpb` from the Releases page.

### Gemini
</details>

Add the following to your Gemini CLI settings file:
<details>
<summary><strong>Claude Desktop, ChatGPT Desktop or Gemini CLI (via <code>npx</code>)</strong></summary>

Add the following to your client's MCP configuration file (`claude_desktop_config.json`, the ChatGPT MCP config, or the Gemini CLI settings file):

```json
{
Expand All @@ -61,7 +64,11 @@ Add the following to your Gemini CLI settings file:
}
```

## Platform Support
</details>

Once configured, restart your client and ask it something like _"list my PCM saves"_ or _"show me the roster of my team"_.

## Platform support

PCM only ships on Windows, where careers live under:

Expand All @@ -71,48 +78,47 @@ PCM only ships on Windows, where careers live under:

Auto-discovery via `pcm_list_saves` is therefore **Windows only**. On macOS/Linux the saves live inside a Wine/Proton prefix that can't be reliably located — pass an absolute `.cdb` path directly to `pcm_select_save` instead.

## Available Tools

All tools are read-only and carry `readOnlyHint: true`, so clients like Claude Desktop can approve them automatically without a confirmation prompt.
## Available tools

| 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). |
| **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`). |
All tools are prefixed with `pcm_`, are read-only, and carry `readOnlyHint: true` so clients like Claude Desktop can approve them automatically without a confirmation prompt.

## Development
| 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). |
| **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`). |

### Build
## How it works

```bash
npm run build
```
Tools are **stateless**: there is no "current save" held by the server. Every save-reading tool takes an absolute `savePath`, re-validates it, and re-reads the `.cdb` from disk into a fresh in-memory SQLite database (via [`cdb-converter`](https://www.npmjs.com/package/cdb-converter) + [`sql.js`](https://www.npmjs.com/package/sql.js)) for each call. The on-disk save is the single source of truth and is never mutated. A typical flow is:

Bundles `src/` to `dist/` with tsup (ESM output).
1. `pcm_list_saves` (Windows) or `pcm_select_save` with an explicit path to locate a save.
2. `pcm_search_cyclist`, `pcm_get_team_roster`, `pcm_query_save`, … to explore it.
3. `pcm_generate_startlist_xml` to produce a startlist file for a race.

### Test

```bash
npm test
```
## Development

### Lint & Format
Clone the repo and install dependencies with `npm install`, then:

```bash
npm run lint # Biome lint with autofixes
npm run format # Biome formatter
npm run build # bundle src/ -> dist/ with tsup (ESM output)
npm test # run the vitest suite once
npm run test:watch # vitest in watch mode
npm run coverage # vitest with v8 coverage
npm run lint # biome lint --write . (autofixes)
npm run format # biome format --write .
npm run pack # produce dist/pcm-mcp.mcpb
Comment thread
mpicciolli marked this conversation as resolved.
```

### Pack a bundle
To debug the server interactively with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):

```bash
npm run pack # produces pcm-mcp.mcpb
npm run build && npm run inspector
```
Loading