# MELCloud AC Control (Python CLI + MCP)

Simple project to control Mitsubishi Electric AC units through MELCloud.

## Goal

This repository is designed as an **LLM-ready execution backend**.
An LLM/agent can interpret natural language and call this project (CLI or MCP) to perform real AC actions.

It supports:
- MELCloud authentication
- device listing
- power on/off per room
- target temperature changes

---

## 1) Requirements

- Python 3.10+
- A MELCloud account with configured devices

Install dependencies:

```bash
cd integrations/melcloud-ac
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
```

---

## 2) Configuration

Create your local environment file:

```bash
cp .env.example .env
```

Fill in your credentials:

```env
MELCLOUD_EMAIL=your_email
MELCLOUD_PASSWORD=your_password
MELCLOUD_LANGUAGE=0
# Optional: lock to a specific building/home name
# MELCLOUD_BUILDING=Home
```

> ⚠️ Never commit `.env`.

---

## 3) Usage

### Option A: CLI (simple)

List devices:

```bash
python control_ac.py list
```

Power control:

```bash
python control_ac.py power office on
python control_ac.py power office off
```

Set temperature:

```bash
python control_ac.py temp office 22
```

Smart automatic control (decides mode + target temperature from room temp):

```bash
python control_ac.py auto office
```

Custom thresholds/targets:

```bash
python control_ac.py auto office --cool-above 26 --heat-below 19 --cool-target 23 --heat-target 22 --neutral-target 23 --neutral-mode auto
```

Notes:
- Device resolution is alias-free and generic: the client fetches your MELCloud devices and picks the best match (with ambiguity safeguards).
- Temperature guardrail in client: 16°C to 31°C.

### Option B: MCP server (for LLM clients)

An MCP wrapper is included in `mcp_server.py` with 4 tools:
- `list_devices()`
- `set_power(room, state)`
- `set_temperature(room, value)`
- `auto_comfort(room, ...)` (smart mode + target temperature selection)

Run MCP server:

```bash
python mcp_server.py
```

Example MCP client configuration (generic):

```json
{
  "mcpServers": {
    "melcloud-ac": {
      "command": "python",
      "args": ["/path/to/integrations/melcloud-ac/mcp_server.py"],
      "env": {
        "MELCLOUD_EMAIL": "...",
        "MELCLOUD_PASSWORD": "...",
        "MELCLOUD_LANGUAGE": "0"
      }
    }
  }
}
```

Tip: you can either pass `env` in your MCP client config or rely on local `.env`.

---

## 4) Project structure

```text
melcloud-ac/
├── control_ac.py        # Main CLI
├── mcp_server.py        # MCP wrapper for LLM tools
├── melcloud_client.py   # MELCloud API client (auth + actions)
├── requirements.txt
├── .env.example
└── README.md
```

---

## 5) LLM integration examples

Typical flow:
1. User says: “Turn on office AC”
2. LLM maps intent to action (`power on`, `room=office`)
3. LLM executes CLI or MCP tool
4. LLM returns a friendly response

Natural language → CLI mapping examples:

- “Turn on office AC”
  - `python control_ac.py power office on`

- “Turn off living room AC”
  - `python control_ac.py power sala off`

- “Set office AC to 22 degrees”
  - `python control_ac.py temp office 22`

- “What devices are available?”
  - `python control_ac.py list`

Quick Python wrapper example:

```python
import json
import subprocess


def ac_command(*args: str) -> dict:
    proc = subprocess.run(
        ["python", "control_ac.py", *args],
        capture_output=True,
        text=True,
        check=False,
    )
    try:
        return json.loads(proc.stdout)
    except json.JSONDecodeError:
        return {"ok": False, "error": proc.stdout or proc.stderr}

print(ac_command("list"))
print(ac_command("power", "office", "on"))
print(ac_command("temp", "office", "22"))
```

Function-calling schema example:

```json
{
  "name": "ac_control",
  "description": "Control MELCloud AC by room",
  "parameters": {
    "type": "object",
    "properties": {
      "action": { "type": "string", "enum": ["list", "power", "temp"] },
      "room": { "type": "string" },
      "state": { "type": "string", "enum": ["on", "off"] },
      "value": { "type": "number" }
    },
    "required": ["action"]
  }
}
```

---

## 6) Quick troubleshooting

- **Login error**: verify email/password and MELCloud account.
- **Room not found**: run `python control_ac.py list` and use the exact device name.
- **Network timeout**: check connectivity and MELCloud availability.

---

## 7) Next improvements (optional)

- consolidated status command
- mode support (`heat/cool/auto`) and fan speed
- automated tests (requests mocking)