BannerlordSage AGENTS.md

BannerlordSage Agent Guide

This repository is a Windows-first MCP server for Mount & Blade II: Bannerlord.

Use this file when an AI coding agent is asked to inspect, install, configure, verify, or run this repo.

Primary Goal

Help the user get BannerlordSage installed and running against a local Bannerlord installation.

What This Repo Does

• imports Bannerlord XML from a local game install
• decompiles official Bannerlord DLLs
• builds SQLite indexes
• exposes MCP tools for Bannerlord querying, modding, and reverse engineering
• can also index and read the user's own local mod source workspace

Important Constraints

• This repo does not include Bannerlord assets
• The user must have a legitimate local Bannerlord installation
• Commands that use --game-dir require the user's real local path
• Never invent a game path; ask for it or discover it from local context
• Do not commit dist/, extracted game assets, SQLite databases, or local secrets

First Files To Read

When you first open this repo, read these files before making assumptions:

1. README.md
2. package.json
3. src/server.ts
4. src/entrypoints/bannerlord-stdio.ts
5. src/entrypoints/bannerlord-full-stdio.ts
6. src/entrypoints/bannerlord-setup.ts

Standard Human Install Flow

If the user wants a normal install, use this order:

1. Install prerequisites:
   • Bun
   • ripgrep
   • .NET SDK 8+
   • ILSpyCmd
2. Install repo dependencies:
   • bun install
3. Run Bannerlord setup:
   • bun run setup:bannerlord -- --game-dir "<BANNERLORD_GAME_DIR>"
   • setup indexes local decompiled source/XML plus public official/community docs and official API search data by default; use --skip-docs only for offline setup
4. Start the MCP server:
   • bun run start:bannerlord

If the user needs the authoring helpers too:

• bun run start:bannerlord:full

MCP Client Config

Recommended MCP entry:

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