BannerlordSage

English | 简体中文

An MCP server for Mount & Blade II: Bannerlord that provides source code search and data browsing.

It reads your local Bannerlord installation, imports XML, decompiles official DLLs, builds a SQLite index, and exposes MCP tools for AI coding agents. Use cases:

• Mod development
• Reverse engineering
• Structured gameplay lookups
• Reading local mod source code

AI-Assisted Install

To have a coding agent (Codex, Claude, Gemini, Copilot, etc.) install and configure this for you:

1. Send the repository URL to the AI
2. Tell it to read AGENTS.md first
3. Tell it to follow AI_QUICKSTART.md
4. Provide your <BANNERLORD_GAME_DIR> when asked

Attribution

BannerlordSage includes work derived from RimSage by Vortex.
The project remains under the MIT License. See LICENSE.

Tool Overview

BannerlordSage provides 37 tools across two entrypoints:

Basic workflow: run setup → start MCP → let the model call tools

Tool List

Diagnostics

Project Memory

Official Source & XML

Official/Community Docs & API

Structured Gameplay Lookups

Local Mod Source

These tools read your own local mod source code, not the official imported source.

Patch & Code Generation

⁺ Only available in start:bannerlord:full.

Common Workflows

Browse official source:

1. search_source — locate the file
2. read_file — read the relevant section
3. read_csharp_type — inspect the type definition

Browse XML or localization:

1. search_xml — locate the file
2. read_file — read the content
3. resolve_localization — resolve tokens

Known game ID, direct lookup:

• Use the structured query tools directly: get_item_stats, trace_troop_tree, get_hero_profile, etc.

Read local mod source:

1. mod_source_status — confirm the workspace
2. search_mod_source — search the code
3. read_mod_file / read_mod_type — read the details

Resume work with project memory:

1. project_memory_wakeup — load the key active context for the workspace
2. project_memory_search — check whether a similar decision, pitfall, or preference already exists
3. project_memory_capture_session — store the useful session output near the end of the task

Daily MCP Usage

Once BannerlordSage is installed and connected to your AI client, the normal daily loop is:

1. Start or resume a task and call project_memory_wakeup
2. Explore official behavior with search_source, read_file, and read_csharp_type
3. Explore your own mod with mod_source_status, search_mod_source, read_mod_file, and read_mod_type
4. Use the structured query tools when you already know an in-game id
5. Before stating project history, call project_memory_search
6. Near the end of the task, call project_memory_capture_session

Project Memory Workflow

Project memory is a local recall layer. It does not change the model's context window. It gives the agent a place to store decisions, pitfalls, preferences, and follow-up state.

Use it like this:

• start a resumed task with project_memory_wakeup
• search memory before claiming project history
• store only durable conclusions
• prefer project_memory_capture_session near task completion
• invalidate old memories when they are no longer true

Installation

1. Prerequisites

• Windows
• A legitimately owned local Bannerlord installation
• Bun
• ripgrep
• .NET SDK 8+
• ILSpyCmd

One-liner to install all dependencies:

powershell -c "irm bun.sh/install.ps1 | iex"
winget install BurntSushi.ripgrep.MSVC
winget install Microsoft.DotNet.SDK.8
dotnet tool install --global ilspycmd

2. Install packages

bun install

3. Run setup

bun run setup:bannerlord -- --game-dir "<BANNERLORD_GAME_DIR>"

Replace <BANNERLORD_GAME_DIR> with the absolute path to your local Bannerlord installation. The first run takes a while; subsequent runs are incremental.

Common flags:

4. Start MCP

# Default (recommended)
bun run start:bannerlord

# Full toolset
bun run start:bannerlord:full

MCP Client Configuration

[mcp_servers.bannerlordsage]
command = "bun"
args = ["run", "src/entrypoints/bannerlord-stdio.ts"]
cwd = "<REPO_DIR>"
enabled = true

Full toolset:

[mcp_servers.bannerlordsage]
command = "bun"
args = ["run", "src/entrypoints/bannerlord-full-stdio.ts"]
cwd = "<REPO_DIR>"
enabled = true

Replace <REPO_DIR> with the absolute path to this repository on your machine.

Environment Variables

Scripts

bun run setup:bannerlord -- --game-dir "<BANNERLORD_GAME_DIR>"   # initialize / update index
bun run start:bannerlord                                         # start default MCP
bun run start:bannerlord:full                                    # start full MCP
bun run verify:memory                                            # verify native project-memory tools
bun run index:gameplay                                           # rebuild gameplay index only
bun run index:docs                                               # index official and community docs
bun run index:api-docs                                           # lightly index all official API symbol versions
bun run index:mod-source -- --source-dir "<MOD_SOURCE_DIR>"     # index local mod source
bun run verify:bannerlord -- --game-dir "<BANNERLORD_GAME_DIR>" # local regression check
bun run smoke:release                                            # quick build validation
bun run report:scopes -- --game-dir "<BANNERLORD_GAME_DIR>"     # output scope report

Project Structure

Disclaimer

This project is for personal learning, research, and mod development with a legitimately owned copy of the game.

1. The repository does not include or redistribute Bannerlord game assets.
2. Users are responsible for complying with the game EULA and applicable local law.
3. Decompiled and indexed content remains local by default.