MCP Xenoforge

A Model Context Protocol (MCP) server for Xenoforge game automation and LLM integration.

Overview

This MCP server enables AI agents to (only when the real Xenoforge game is actually running and reachable):

• Capture real screenshots of the running Xenoforge game window
• (Experimental / minimal) Interact with the game by clicking explicit screen coordinates only
• Retrieve real game state data (currently limited; returns empty structures when unavailable)
• (Planned) Execute automated gameplay sequences (workflows scaffold only)
• (Planned) Analyze game performance metrics

Important:

• No simulated / mock / placeholder / random data is ever returned.
• If the game is not running or not yet connected, tools return deterministic empty results plus a status message describing the missing precondition.
• Features listed as Planned will currently respond with a not-implemented status instead of fabricating data.

Features

Core MCP Tools (Current Real Behavior)

• capture_screenshot – Captures an actual screenshot ONLY if the game window is detected; otherwise returns a clear message (no image data fabricated).
• click_ui_element – Currently supports coordinate-based clicks only. Text / type-based targeting is NOT implemented and will return a deterministic not-implemented response.
• get_game_state – Returns only what the live integration can read (presently minimal). When disconnected, returns empty objects and a status note.
• send_key_sequence – (Planned) Not yet implemented; returns not-implemented.
• run_automation_workflow – (Scaffold) Returns not-implemented until real workflows are added.
• analyze_ui_elements – (Planned) OCR / element discovery not yet active; returns not-implemented.
• monitor_game_performance – (Planned) Metrics collection not yet implemented.

All unimplemented tools intentionally return a standardized structure with success: false and error describing the limitation—never synthetic data.

Automation Workflows

Workflow scaffolding exists, but NO automated gameplay logic ships yet. All workflow invocations return a not-implemented response. No heuristic or mock resource collection is performed.

Installation

# Install dependencies
npm install

# Build the server
npm run build

# Start the MCP server
npm start

Development

# Development mode with hot reload
npm run dev

# Watch mode for TypeScript compilation
npm run watch

# Lint code
npm run lint

# Format code
npm run format

Game Integration Setup

1. Start Xenoforge Game

   # From the Xenv6 workspace
   ./gradlew.bat :desktop:run
   

2. Launch MCP Server

   # From the Mcp-Xenoforge workspace
   npm start
   

3. Run Automation Session

   # Starts both game and MCP server together
   npm run start:automation
   

Configuration

Create a .env file in the project root:

GAME_WINDOW_TITLE=Xenoforge
NODE_ENV=development
LOG_LEVEL=info
SCREENSHOT_INTERVAL=1000
MAX_RETRIES=3
TIMEOUT_MS=30000
ENABLE_OCR=true
ENABLE_IMAGE_ANALYSIS=true

MCP Tool Usage Examples

Capture Screenshot

{
  "name": "capture_screenshot",
  "arguments": {
    "windowTitle": "Xenoforge",
    "region": "full",
    "includeAnalysis": true
  }
}

If the game window is not found, the response will be:

{
  "success": false,
  "error": "Game window not found or not running.",
  "timestamp": 1234567890
}

Click UI Element (Coordinates Only)

{
  "name": "click_ui_element",
  "arguments": {
    "x": 640,
    "y": 360,
    "waitAfter": 250
  }
}

Text / semantic element targeting is not implemented and will return a not-implemented error if such parameters are supplied.

Get Game State

{
  "name": "get_game_state",
  "arguments": {
    "includeResources": true,
    "includeUnits": true,
    "includeBuildings": true
  }
}

When disconnected, an example response:

{
  "success": true,
  "data": {
    "connected": false,
    "resources": {},
    "units": [],
    "buildings": []
  },
  "timestamp": 1234567890
}

Run Automation Workflow (Not Implemented)

{
  "name": "run_automation_workflow",
  "arguments": {
    "workflowId": "collect_resources"
  }
}

Response:

{
  "success": false,
  "error": "Workflow execution not implemented.",
  "timestamp": 1234567890
}

Architecture

src/
├── index.ts                 # Main MCP server entry point
├── types/                   # TypeScript type definitions
│   └── index.ts
├── tools/                   # MCP tool implementations
│   ├── screenshot-capture.ts
│   ├── ui-interaction.ts
│   └── game-state-monitor.ts
├── game/                    # Game integration layer
│   └── game-integration.ts
└── automation/              # Automation engine
    ├── automation-engine.ts
    └── game-controller.ts

Dependencies

Core Dependencies

• @modelcontextprotocol/sdk - MCP protocol implementation
• screenshot-desktop - Screen capture functionality
• robotjs - UI automation and input simulation
• jimp - Image processing and manipulation
• sharp - High-performance image processing
• tesseract.js - OCR (Optical Character Recognition)

Development Dependencies

• TypeScript - Type-safe JavaScript
• ESLint - Code linting
• Prettier - Code formatting

Integration with Xenoforge

This MCP server is designed to work with the Xenoforge game project:

• Xenv6 - Main game implementation
• Forge-Core - Game engine foundation
• Mcp-Xenoforge - This automation layer

Usage in LLM Applications

This MCP server can be used with LLM applications to enable AI agents to:

1. Play the game autonomously by analyzing screenshots and making decisions
2. Assist human players by providing automation for repetitive tasks
3. Test game features through automated gameplay scenarios
4. Monitor performance and provide optimization suggestions
5. Generate gameplay data for analysis and improvement

API Documentation

Tool Schemas

All tools follow the MCP tool schema format with:

• name - Tool identifier
• description - What the tool does
• inputSchema - JSON schema for tool parameters

Response Format

All tools return a standardized response:

{
  success: boolean;
  data?: any;
  error?: string;
  timestamp: number;
}

Operational Behavior & Troubleshooting

Gating & Deterministic Output

• If prerequisites (running game, detectable window, established integration) are missing, tools return either success: false with an explanatory error, or success: true with empty data and connected: false.
• No retries or backoff loops fabricate interim data.

Common States

1. Game not started – Most tools return not-found / disconnected messages.
2. Game starting – Brief window where screenshot capture may fail; retry manually once the window is stable.
3. Not implemented feature invoked – Returns standardized not-implemented error.

Issue Diagnosis Checklist

• Confirm the game desktop client is running before invoking tools.
• Verify window title matches GAME_WINDOW_TITLE exactly.
• Ensure no fullscreen exclusive mode prevents capture (use windowed / borderless if needed).
• Provide explicit coordinates for clicks (semantic selection not yet available).

Planned Enhancements (Not Yet Available)

• OCR-based UI element discovery
• Semantic UI interaction (by text / role)
• Performance metrics pipeline
• Real automation workflow execution
• Rich game state ingestion (resources, units, structures) via direct instrumentation

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Run linting and formatting
6. Submit a pull request

License

MIT License - see LICENSE file for details.