# cfb-recruiting-mcp

An MCP (Model Context Protocol) server that **diagnoses and fixes CFB 27 dynasty
recruiting** by editing the dynasty save. It targets the community's biggest
recruiting complaint: the game floods the class with 1–2 star recruits, so a huge
share of real 4–5 star prospects never get scholarship offers, never sign, and
**disappear**.

The reverse-engineered recruiting data model is **baked into the tools**, so any
model — not just a top-tier one — can run the whole workflow by calling a few
high-level tools. It does the table joins, the star-by-signing math, and the pool
edits for you.

```
┌────────────┐   MCP (stdio)   ┌───────────────────┐        ┌──────────────────┐
│ LLM client │ ◄─────────────► │ cfb-recruiting-mcp │ ◄────► │ madden-franchise │ ◄── DYNASTY-* save
└────────────┘                 └───────────────────┘        └──────────────────┘
```

## What it found on a real save (verified)

Running `recruiting_diagnose` on a real dynasty reproduced the complaint exactly:

- **3,764 high-school recruits; 55% of them 1–2 star** — massive pool bloat.
- **45% of 4-star recruits unsigned** (195 of 430). Even 12% of 5-stars unsigned.
- **66 unsigned 4–5 star recruits with ZERO scholarship offers** — including the
  #5 recruit in the country with no offers. These never sign and vanish.

## Tools

- **recruiting_open** `{ file_path }` — open a DYNASTY-* save (full CFB 27 schema
  applied automatically).
- **recruiting_diagnose** `{ file_path }` — full pool health report: star
  distribution, signed-vs-unsigned per star tier, unsigned recruits with zero
  offers, and a plain-English interpretation. Read-only.
- **recruiting_list_recruits** `{ file_path, stars?, signed?, zero_offers_only? }`
  — drill into a specific cohort (e.g. unsigned 4–5 stars). Read-only.
- **recruiting_prune_low_stars** `{ file_path, stars?, dry_run }` — remove low-star
  recruits (default 1–2 star, HS only) to unclog the pool. Dry-run by default.
- **recruiting_save** `{ file_path }` — write edits to disk (timestamped backup).
- **recruiting_close** `{ file_path }`.

## Setup

```bash
# alongside a clone of bep713/madden-franchise (this depends on it via file:)
npm install
npm run build
```

Register with an MCP client (e.g. Claude Code `.mcp.json`):

```json
{
  "mcpServers": {
    "cfb-recruiting": { "command": "node", "args": ["<path>/cfb-recruiting-mcp/dist/index.js"] }
  }
}
```

## Important: what this can and cannot do

- The recruiting **AI/engine is compiled into the game** — not moddable. This tool
  changes the **save-file data** the AI works on (the recruit pool), not its
  behavior. Fewer junk recruits ⇒ the AI spreads itself less thin.
- Every change is a **save edit** with an automatic backup. **Verify results
  in-game** and restore the `.backup-*` file if anything looks wrong.
- `recruiting_prune_low_stars` is **experimental**: it removes recruits by setting
  their stage to `Invalid` and burying rank/offers. Whether that fully clears them
  from in-game boards needs playtesting — feedback welcome.

## Credits

Built on [bep713/madden-franchise](https://github.com/bep713/madden-franchise).
Full CFB 27 schema (major 809) extraction method by
[brooksg357-a11y/cfb27-dynasty-modding](https://github.com/brooksg357-a11y/cfb27-dynasty-modding).
Part of a free community modding suite by [@RoamingAnalyst](https://x.com/RoamingAnalyst).

## License

MIT.