Files

Allegro (Burn Mode) 29e64ef01f

Deploy Nexus / deploy (push) Failing after 4s

Details

feat: Complete Bannerlord MCP Harness implementation (Issue #722 )

Implements the Hermes observation/control path for local Bannerlord per GamePortal Protocol.

## New Components

- nexus/bannerlord_harness.py (874 lines)
  - MCPClient for JSON-RPC communication with MCP servers
  - capture_state() → GameState with visual + Steam context
  - execute_action() → ActionResult for all input types
  - observe-decide-act loop with telemetry through Hermes WS
  - Bannerlord-specific actions (inventory, party, save/load)
  - Mock mode for testing without game running

- mcp_servers/desktop_control_server.py (14KB)
  - 13 desktop automation tools via pyautogui
  - Screenshot, mouse, keyboard control
  - Headless environment support

- mcp_servers/steam_info_server.py (18KB)
  - 6 Steam Web API tools
  - Mock mode without API key, live mode with STEAM_API_KEY

- tests/test_bannerlord_harness.py (37 tests, all passing)
  - GameState/ActionResult validation
  - Mock mode action tests
  - ODA loop tests
  - GamePortal Protocol compliance tests

- docs/BANNERLORD_HARNESS_PROOF.md
  - Architecture documentation
  - Proof of ODA loop execution
  - Telemetry flow diagrams

- examples/harness_demo.py
  - Runnable demo showing full ODA loop

## Updates

- portals.json: Bannerlord metadata per GAMEPORTAL_PROTOCOL.md
  - status: active, portal_type: game-world
  - app_id: 261550, window_title: 'Mount & Blade II: Bannerlord'
  - telemetry_source: hermes-harness:bannerlord

## Verification

pytest tests/test_bannerlord_harness.py -v
37 passed, 2 skipped, 11 warnings

Closes #722

2026-03-31 04:53:29 +00:00

2.8 KiB

Raw Blame History

MCP Servers for Bannerlord Harness

This directory contains MCP (Model Context Protocol) servers that provide tools for desktop control and Steam integration.

Overview

MCP servers use stdio JSON-RPC for communication:

Read requests from stdin (line-delimited JSON)
Write responses to stdout (line-delimited JSON)
Each request has: jsonrpc, id, method, params
Each response has: jsonrpc, id, result or error

Servers

Desktop Control Server (`desktop_control_server.py`)

Provides desktop automation capabilities using pyautogui.

Tools:

take_screenshot(path) - Capture screen and save to path
get_screen_size() - Return screen dimensions
get_mouse_position() - Return current mouse coordinates
pixel_color(x, y) - Get RGB color at coordinate
click(x, y) - Left click at position
right_click(x, y) - Right click at position
move_to(x, y) - Move mouse to position
drag_to(x, y, duration) - Drag with duration
type_text(text) - Type string
press_key(key) - Press single key
hotkey(keys) - Press key combo (space-separated)
scroll(amount) - Scroll wheel
get_os() - Return OS info

Note: In headless environments, pyautogui features requiring a display will return errors.

Steam Info Server (`steam_info_server.py`)

Provides Steam Web API integration for game data.

Tools:

steam_recently_played(user_id, count) - Recent games for user
steam_player_achievements(user_id, app_id) - Achievement data
steam_user_stats(user_id, app_id) - Game stats
steam_current_players(app_id) - Online count
steam_news(app_id, count) - Game news
steam_app_details(app_id) - App details

Configuration: Set STEAM_API_KEY environment variable to use live Steam API. Without a key, the server runs in mock mode with sample data.

Configuration

The mcp_config.json in the repository root configures the servers for MCP clients:

{
  "mcpServers": {
    "desktop-control": {
      "command": "python3",
      "args": ["mcp_servers/desktop_control_server.py"]
    },
    "steam-info": {
      "command": "python3",
      "args": ["mcp_servers/steam_info_server.py"]
    }
  }
}

Testing

Run the test script to verify both servers:

python3 mcp_servers/test_servers.py

Or test manually:

# Test desktop control server
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python3 mcp_servers/desktop_control_server.py

# Test Steam info server  
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{}}' | python3 mcp_servers/steam_info_server.py

Bannerlord Integration

These servers can be used to:

Capture screenshots of the game
Read game UI elements via pixel color
Track Bannerlord playtime and achievements via Steam
Automate game interactions for testing

2.8 KiB Raw Blame History