franchise-mcp-server

An MCP (Model Context Protocol) server that lets LLMs read and edit Madden NFL franchise saves and EA SPORTS College Football dynasty saves (CFB 27+). It wraps bep713/madden-franchise — the community-standard parser behind tools like Franchise Editor — and exposes its full capability as 14 well-guarded tools.

Supported games (inherited from the library): Madden 19–27, College Football 27+. Both franchise saves and FTC (franchise-common) game-data files open.

┌────────────┐     MCP (stdio)     ┌─────────────────────┐        ┌──────────────────┐
│ LLM client │ ◄─────────────────► │ franchise-mcp-server │ ◄────► │ madden-franchise │ ◄── CAREER-* / DYNASTY-* files
└────────────┘                     └─────────────────────┘        └──────────────────┘

Layout

franchise-mcp-server/
├── src/                 TypeScript source
│   ├── index.ts         server + tool registrations
│   ├── session.ts       open-file sessions, table resolution, field loading
│   ├── serialize.ts     field value ⇄ JSON conversion, validation, pagination
│   ├── types.ts         structural types for the library
│   └── constants.ts
├── dist/                built JS (entry: dist/index.js)
├── tests/smoke-test.mjs end-to-end test (drives the server over stdio)
└── skills/franchise-editor/          ← docs for LLM agents
    ├── SKILL.md                       main skill (workflow + safety rules)
    └── references/
        ├── domain-model.md            file anatomy, references, free-lists
        ├── workflows.md               step-by-step recipes
        ├── cfb-notes.md               CFB 27 dynasty specifics
        └── library-api.md             building apps on the library directly

Setup

Requires Node.js >= 22.19.0.

This server depends on madden-franchise via file:../madden-franchise — clone it as a sibling directory (the repo version includes CFB 27 support that is ahead of the npm release):

# 1. Clone both repos side by side
git clone https://github.com/bep713/madden-franchise.git
git clone https://github.com/<you>/franchise-mcp-server.git

# 2. Build the library
cd madden-franchise && npm install && npm run build

# 3. Build the server
cd ../franchise-mcp-server && npm install && npm run build

# 4. Smoke test against bundled CFB 27 test data (uses a copy!)
cp ../madden-franchise/tests/data/DYNASTY-27COMPRESS /tmp/DYNASTY-TEST
node tests/smoke-test.mjs /tmp/DYNASTY-TEST

Register with Claude Code (project .mcp.json)

{
  "mcpServers": {
    "franchise": {
      "command": "node",
      "args": ["<absolute-path-to>/franchise-mcp-server/dist/index.js"]
    }
  }
}

Register with Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "franchise": {
      "command": "node",
      "args": ["<absolute-path-to>/franchise-mcp-server/dist/index.js"]
    }
  }
}

Give the agent the skills/franchise-editor/ folder (Claude Code discovers it from .claude/skills/; other agents can be pointed at SKILL.md directly).

Tool catalog

File lifecycle

Tool	Purpose
franchise_open	Open a CAREER-/DYNASTY- file into a session. Options: auto_unempty (needed to add rows), game_year_override, game_type_override. Returns game/schema info.
franchise_save	Persist changes — overwrite, or output_path to save-as. Nothing is written to disk without this.
franchise_close	Close a session, discarding unsaved changes.
franchise_list_open_files	Sessions + which tables have unsaved changes.

Discovery

Tool	Purpose
franchise_list_tables	Browse/filter the ~2,000+ tables (name, uniqueId, record count, capacity, isArray).
franchise_get_table_schema	Field definitions: type, min/max, maxLength, enum members, reference-ness, storage section.

Reading

Tool	Purpose
franchise_read_records	Paginated row reads with field selection; row_indices for specific rows; array tables return ordered reference lists.
franchise_get_record	Every field of one row, field-paginated (Player has ~300 fields).
franchise_search_records	Find rows by field conditions (eq/neq/contains/gt/gte/lt/lte), e.g. player by name.

Writing

Tool	Purpose
franchise_edit_records	Batch field edits with validation: range-checked ints, length-checked strings, enum-name checking, references as {tableId,row}/{tableUniqueId,row}/null, JSON blobs (CharacterVisuals). Echoes old→new values. Blocks writes to empty records unless auto_unempty.

References & row lifecycle

Tool	Purpose
franchise_resolve_reference	Decode 32-bit refs (binary string, asset id, or tableId+row) to table name/uniqueId/row.
franchise_find_references_to_record	Which tables point at a record (run before removing/repurposing anything).
franchise_get_empty_records	Free-list state: nextRecordToUse, empty-row chain — the safe way to add rows.
franchise_recalculate_empty_records	Rebuild the free-list after bulk operations.

Design notes

• Validation-first writes. The underlying library bit-packs values and will silently wrap out-of-range ints and corrupt free-lists if misused; this server rejects out-of-range/oversized/invalid-enum writes and empty-record writes with errors that state the valid values.
• Stable identity. Tools push agents toward table_unique_id (stable across files and game years) over file-specific tableIds and ambiguous names.
• Context-efficient. Everything is paginated and field-selectable; responses over ~25k chars truncate with explicit truncated_by_size + next_offset metadata.
• Edit-safe partial reads. Field lists load incrementally; pending edits are flushed to the table buffer before any re-read, so partial reads never lose unsaved changes.
• Sessions. Multiple files can be open at once (e.g. copy data between a Madden franchise and a CFB dynasty, or between a save and its backup).

Known table uniqueIds

Table	uniqueId	Verified
Player	1612938518	Madden 25/26, CFB 27
CharacterVisuals	1429178382	CFB 27

Everything else: discover per-file with franchise_list_tables (name collisions are common — eight tables named Team exist in CFB 27; pick by record count).

License

MIT (the wrapped madden-franchise library is MIT by matthewpanetta/bep713).