BannerlordSage

English | 简体中文

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

Editor MCP is an experimental test version — PRs welcome! Local editor authoring is currently validated against an aligned Bannerlord game and Modding Kit v1.4.8. Prefab layout, scene saving and viewport capture have been tested; terrain editing, playable Missions, navigation and sailing are not yet validated. Submit a PR or report an issue.

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 `` when asked

Attribution

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

Tool Overview

BannerlordSage provides 43 tools across two entrypoints:

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

Tool List

Diagnostics

Local Editor — Experimental

Status is available in both entrypoints; the other five tools require full mode. Install the local C# bridge and open its dedicated scene first, then pass an optional absolute local sessionPath or set BANNERSAGE_EDITOR_PROBE_SESSION in the MCP service environment. The session JSON contains a local credential and must stay out of Git. Public tools do not launch, replace, reload or close scenes. See setup, CLI, blueprints and tested limits.

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 ""

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

Setup also indexes public official/community documentation and official API search data by default. The docs/API data is stored in the local SQLite database, reused on later runs, and only refreshed when missing or when --reindex-docs is passed. Use --skip-docs for offline or local-only setup.

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 = ""
enabled = true

Full toolset:

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

Replace `` with the absolute path to this repository on your machine.

Environment Variables

Scripts

bun run setup:bannerlord -- --game-dir ""   # initialize/update local and public docs indexes
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                                               # manually refresh official and community docs
bun run index:api-docs                                           # manually refresh official API symbol versions
bun run index:mod-source -- --source-dir ""     # index local mod source
bun run verify:bannerlord -- --game-dir "" # local regression check
bun run smoke:release                                            # quick build validation
bun run report:scopes -- --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.