# Titan Rotation MCP

Даёт твоему ИИ (Claude Code, Codex, Cursor, Claude Desktop) знания Titan SDK, проверенные spell ID и валидатор Lua — чтобы ротация для **любого класса и спека** делалась одним промтом.

```
Сделай ротацию для монка-хила
```

ИИ сам вызывает инструменты, собирает Lua и проверяет код. Ты платишь только за свою подписку — никаких сторонних ключей и серверов.

*[English below](#english)*

---

## Установка

Нужны **Node.js 18+** и компилятор Lua (для проверки синтаксиса).

```bash
# Debian/Ubuntu
sudo apt install lua5.4
# macOS
brew install lua
# Windows
scoop install lua
```

Добавь сервер в конфиг своего клиента.

**Claude Code** (`~/.claude/mcp.json` или `.mcp.json` в проекте):

```json
{
  "mcpServers": {
    "titan": {
      "command": "npx",
      "args": ["-y", "titan-rotation-mcp"]
    }
  }
}
```

**Claude Desktop** (`claude_desktop_config.json`), **Cursor** (`~/.cursor/mcp.json`) — тот же блок.

Или поставить глобально:

```bash
npm install -g titan-rotation-mcp
```

```json
{
  "mcpServers": {
    "titan": { "command": "titan-rotation-mcp" }
  }
}
```

Проверить, что запускается:

```bash
npx -y titan-rotation-mcp
# Titan Rotation MCP v1.0.0 запущен (stdio). Lua-компилятор: luac5.4
```

---

## Как пользоваться

Просто попроси ротацию:

> Сделай ротацию для Mistweaver Monk

> Ротацию для гардиан друида, с настройками дефансивов

> Ротация для рестор шамана, Lay on Hands-подобные кнопки — выбор цели через настройку

ИИ вызовет `titan_start_rotation`, получит всё нужное одним ответом (identity, роль, приоритеты, spell ID, шаблон), напишет Lua и проверит через `titan_validate_rotation`. Готовый код вставляешь в Titan.

Понимает синонимы: `mw`, `resto`, `prot`, `bear`, `boomkin`, `dk`, `dh`.

---

## Что внутри

Поддержаны **все 40 спеков** 13 классов, включая Devourer (третий спек Demon Hunter в Midnight). Spec ID и роли сверены с игровыми данными DB2.

| Инструмент | Зачем |
|---|---|
| `titan_start_rotation` | Всё для старта одним вызовом: identity, роль, приоритеты, ID, шаблон |
| `titan_get_role_blueprint` | Порядок принятия решений для healer / tank / dps |
| `titan_get_spec_data` | SimC APL + числовые spell ID |
| `titan_resolve_spell_ids` | ID по именам способностей (для спеков без APL) |
| `titan_get_settings_format` | Формат настроек в Lua (bool/int/enum, группы) |
| `titan_get_healing_primitives` | Рабочий Lua: выбор цели, heal absorb, политики таргетинга |
| `titan_validate_rotation` | Синтаксис + существование API + полнота по роли |
| `titan_list_api_methods` | 455 методов с сигнатурами |
| `titan_get_signature` | Сигнатура одного метода |
| `titan_list_docs` / `titan_get_doc` / `titan_search_docs` | Документация SDK (24 темы) |
| `titan_get_template` | Канонический шаблон модуля |
| `titan_get_example` | Эталонная ротация Holy Paladin (1205 строк) |
| `titan_list_specs` | Все классы и спеки с id и ролями |

---

## Почему это работает лучше, чем «просто спросить ИИ»

**Выдуманные методы отклоняются.** Валидатор сверяет каждый вызов `api.*` с реестром из 455 реальных методов. Написал `api.get_lowest_health()` вместо `api.get_lowest_unit()` — получит ошибку и исправит сам.

**Spell ID берутся из игровых данных, а не из памяти модели.** Резолвер тянет DB2-дампы с wago.tools и ограничивает поиск пулом заклинаний класса (спеллбук + дерево талантов). Поэтому `thrash` у друида не превращается в чужой одноимённый спелл — из 74 кандидатов по имени остаются только те, что реально есть у класса.

**Приоритеты — из SimulationCraft**, с актуальной ветки и версии клиента, а не «как было в прошлом аддоне».

**Для хилов честно сказано, что источника истины нет.** В SimC 34 файла APL, и лечения там нет: симулятор считает урон по неподвижной цели, а лечение реактивно. Единственный «хилерский» APL — `druid_restoration`, где вся лечебная часть это `strict_sequence:regrowth:regrowth:regrowth:regrowth`, остальное DPS в кошке. Вместо того чтобы дать ИИ выдумывать, MCP отдаёт blueprint роли: порядок принятия решений, какими методами, что должно быть настройкой игрока, какие ошибки типичны.

**Ролевая проверка ловит пустышки.** Ротация хила без выборки цели лечения компилируется прекрасно и не лечит. Такое отклоняется как ошибка, а не пропускается:

```
VALID: false
✓ Синтаксис Lua OK (luac5.4)
✗ РОЛЬ: Нет выбора цели лечения (get_lowest_unit / get_group /
  get_friendly_units_with_range). Хил, который лечит только текущую цель,
  в рейде бесполезен.
```

Для танка так же: нет active mitigation или контроля агро — ошибка. SimC APL этот слой не описывает вообще, потому что не моделирует входящий бурст.

**Формат настроек — реальный.** Официальная дока описывает только C++ (`SettingsSchema`, `make_enum`); в Lua он не работает. MCP отдаёт формат, который действительно применяется, включая enum для политик игрока:

```lua
{ id = "loh_mode", type = "enum", label = "Lay on Hands", default = 1,
  group = "lay_on_hands",
  enum_options = {
      { value = 0, label = "Не использовать" },
      { value = 1, label = "Только на себя" },
      { value = 2, label = "Только на танка" },
      { value = 3, label = "Себя и танка" },
      { value = 4, label = "На всех" },
  } },
```

---

## Работает автономно

Все данные считаются на твоей машине: SimC-приоритеты идут напрямую с GitHub, spell ID — с wago.tools. Никаких промежуточных серверов, никакой телеметрии, никаких ключей.

Первый резолв ID качает ~14 МБ DB2-таблиц в `~/.titan-mcp/cache` и живёт неделю. Дальше мгновенно. Кэш переносится через `TITAN_CACHE_DIR`.

---

## Разработка

```bash
git clone https://github.com/brooke19931993-glitch/titan-rotation-mcp.git
cd titan-rotation-mcp
npm install

npm test              # юнит-тесты (без сети)
node test/e2e.mjs     # живой прогон через stdio (нужна сеть)
```

---

## Оговорки

- Инструмент помогает **писать код**; за использование сторонних аддонов в игре ответственность на тебе.
- Spell ID меняются с патчами. Кэш сам обновляется через неделю, принудительно — удали `~/.titan-mcp/cache`.
- Неоднозначные ID (несколько кандидатов внутри класса) отдаются списком: выбор за ИИ или за тобой, проверяй на Wowhead.
- Blueprint роли — это каркас и порядок решений, а не готовый тюнинг под конкретный рейд. Пороги настраиваются в игре.

---

<a name="english"></a>

# English

MCP server that gives your AI (Claude Code, Codex, Cursor) the Titan addon SDK knowledge, verified spell IDs and a Lua validator — so a combat rotation for **any class and spec** can be made from a single prompt.

```
Write a rotation for Mistweaver Monk
```

## Install

Requires **Node.js 18+** and a Lua compiler (`sudo apt install lua5.4` / `brew install lua` / `scoop install lua`).

```json
{
  "mcpServers": {
    "titan": {
      "command": "npx",
      "args": ["-y", "titan-rotation-mcp"]
    }
  }
}
```

## Why it beats asking an AI directly

- **Invented API methods are rejected** — every `api.*` call is checked against a registry of 455 real methods.
- **Spell IDs come from game data** (wago.tools DB2), scoped to the class spell pool, not from model memory.
- **Priorities come from SimulationCraft**, current branch and client version.
- **For healers it admits there is no source of truth.** SimC has 34 APL files and none of them model healing (the only "healer" APL, `druid_restoration`, reduces healing to `strict_sequence:regrowth:regrowth:regrowth:regrowth`). Instead of letting the AI invent priorities, the server provides a role blueprint: decision order, which API methods to use, what must be a player setting, and common mistakes.
- **Role validation catches empty shells.** A healer rotation with no ally targeting compiles fine and heals nobody — that is reported as an error, not a warning. Same for tanks missing active mitigation.
- **The settings format is the real one.** Official docs only describe the C++ API, which does not work in Lua.

All data is computed locally: SimC from GitHub, spell IDs from wago.tools. No intermediate servers, no telemetry, no API keys. First ID resolve caches ~14 MB of DB2 tables in `~/.titan-mcp/cache` for a week.

All 40 specs across 13 classes are supported, including Devourer (the third Demon Hunter spec in Midnight). Spec IDs and roles are verified against DB2 game data.

## License

MIT