# mcp-azureland

MCP server for managing [AzurLaneAutoScript](https://github.com/LmeSzinc/AzurLaneAutoScript) (ALAS) and other game automation scripts via AI agents.

> **Status**: Phase 1 — Core process management, config tools, and monitoring.

## Overview

`mcp-azureland` exposes ALAS as a set of MCP tools, enabling AI agents (OpenClaw, Hermes, Cursor, Claude Code, etc.) to:

- **Start/stop** ALAS automation processes
- **Read/write** ALAS JSON config files
- **Monitor** runtime status via logs and screenshots
- **Schedule** tasks (daily, campaign farming, event farming, etc.)

### Design principles

| Principle | Implementation |
|-----------|---------------|
| **Zero intrusion** | Never imports or modifies ALAS source code |
| **Subprocess-based** | ALAS runs as a subprocess via bridge script |
| **Filesystem IPC** | Reads configs, logs, screenshots from ALAS filesystem |
| **Windows native** | Process management optimized for Windows |
| **Extensible** | Abstract adapter interface for future game scripts |

## Quick Start

### Prerequisites

- Python 3.10+
- [AzurLaneAutoScript](https://github.com/LmeSzinc/AzurLaneAutoScript) installed and configured
- Windows (recommended)

### Installation

```bash
# Clone and install
git clone git@github.com:Wislist/mcp-azureland.git
cd mcp-azureland
pip install -e .
```

### Configuration

Edit `config/server.yaml` to set the path to your ALAS installation:

```yaml
alas_path: "D:/Games/AzurLaneAutoScript"  # Absolute or relative path
```

### Run

```bash
# Directly
python -m mcp_azureland.server

# Or via installed command
mcp-azureland
```

### MCP Client Setup

Add to your AI agent's MCP configuration:

```json
{
  "mcpServers": {
    "azureland": {
      "command": "python",
      "args": ["-m", "mcp_azureland.server"],
      "cwd": "/path/to/mcp-azureland"
    }
  }
}
```

## MCP Tools

### Process Management

| Tool | Description |
|------|-------------|
| `alas_start` | Start ALAS scheduler or run single task |
| `alas_stop` | Stop a running ALAS process |
| `alas_status` | Get process status |
| `alas_list_tasks` | List all available automation tasks |

### Configuration

| Tool | Description |
|------|-------------|
| `config_list` | List all ALAS config files |
| `config_get` | Read config values |
| `config_set` | Set config values |
| `schedule_manage` | Enable/disable scheduler tasks |

### Monitoring

| Tool | Description |
|------|-------------|
| `alas_logs` | Read recent log output |
| `alas_status_detail` | Parse log for status summary |
| `alas_screenshot` | Get latest error screenshot |
| `alas_statistics` | Read farming statistics |

## Architecture

```
AI Agent (OpenClaw/Hermes)
    │ MCP stdio (JSON-RPC)
    ▼
mcp-azureland server
    │
    ├── ProcessManager  ── subprocess ──► bridge/run_alas.py ── import ──► ALAS
    ├── ConfigManager   ── read/write ──► config/*.json
    └── MonitorManager  ── tail/read ───► log/*.txt, screenshots/
```

## Extending

To add support for another game:

1. Create a new adapter in `src/mcp_azureland/adapters/`
2. Inherit from `BaseGameAdapter` and implement the abstract methods
3. Register the adapter in `server.py`

See [adapters/base.py](src/mcp_azureland/adapters/base.py) for the interface.

## License

MIT