# MCP-Orchestrator

**State Machine & Git Workflow Engine для AI-агентов**

MCP-Orchestrator — это MCP-сервер, который превращает хаотичную работу AI-агентов в управляемый, изолированный и аудитируемый процесс. В основе лежит принцип **SPEC → PLAN → AGENTS**: агенты работают не напрямую с кодом, а через три управляющих файла, а сервер контролирует состояния, ветки Git и целостность проекта.

---

## Концепция

```
┌─────────────────────────────────────────────────────┐
│                    MCP-Orchestrator                   │
│                                                       │
│   SPEC.md ──► PLAN.md ──► AGENTS.md                  │
│      ↑            ↑             ↑                     │
│   Что?         Как?         Что сделано?             │
│                                                       │
│   ┌──────────────┬──────────────┬────────────────┐    │
│   │ State Machine │  Git Engine  │  File Parser   │    │
│   └──────────────┴──────────────┴────────────────┘    │
│                                                       │
│   Tools: get_project_state │ start_phase │ commit     │
│          complete_phase   │ fail_phase                │
└─────────────────────────────────────────────────────┘
```

AI-агент никогда не пишет код напрямую в `main`. Он:

1. Запрашивает состояние проекта (`get_project_state`)
2. Запускает фазу (`start_phase`) — сервер создаёт изолированную Git-ветку `feature/phase_id`
3. Пишет код внутри этой ветки
4. Фиксирует прогресс (`commit_phase`)
5. Завершает фазу (`complete_phase`) — сервер вливает ветку в `main`, обновляет `PLAN.md` и пишет лог в `AGENTS.md`

---

## Три управляющих файла

| Файл | Роль |
|---|---|
| `SPEC.md` | **Спецификация проекта.** Что нужно построить? Какие правила и ограничения? |
| `PLAN.md` | **План работ.** Разбивка на фазы, зависимости, статусы (`pending → in_progress → completed / failed`), режим выполнения (`parallel: true/false`) |
| `AGENTS.md` | **Чёрный ящик.** Аудит-лог всех завершённых фаз: кто, что и когда сделал, какие были проблемы |

Каждый файл содержит YAML Front Matter, который сервер парсит, валидирует и обновляет.

---

## Архитектура

### State Machine (`src/state_machine.py`)

In-memory конечный автомат для отслеживания жизненного цикла фаз.

- **Статусы:** `pending → in_progress → completed / failed`
- **Защита от AI Looping:** блокировка после 3 неудачных попыток перезапуска фазы
- **Бэкапы:** in-memory снимки `SPEC.md`, `PLAN.md`, `AGENTS.md` перед каждым инструментом
- **Автовосстановление:** при повреждении `PLAN.md` файл откатывается из бэкапа

### File Parser (`src/file_parser.py`)

Парсер YAML Front Matter с двусторонней сериализацией.

- Читает `PLAN.md` в структурированные `PlanFileData` / `PhaseData`
- Записывает обновления без потери текстового описания шагов
- Валидирует: обязательные поля (`id`, `name`), допустимые статусы, уникальность ID, корректность зависимостей

### Git Engine (`src/git_operations.py`)

Управление ветками и изоляцией через системный Git.

- `start_phase` → проверка чистоты репозитория, создание `feature/phase_id`
- `commit_phase` → `git add . && git commit -m "<message>"`
- `complete_phase` → `git merge --no-ff` в `main`, удаление feature-ветки
- `fail_phase` → `git reset --hard` к точке расхождения, удаление ветки
- **Конфликт-анализ:** при параллельных фазах проверяет `git diff --name-only` и блокирует запуск при пересечении файловых скоупов

### MCP Server (`src/server.py`)

Интеграция всего в 5 MCP-инструментов (см. ниже).

---

## MCP-инструменты

| Инструмент | Параметры | Действие |
|---|---|---|
| `get_project_state` | — | Возвращает матрицу фаз, доступные для запуска, подсказку о параллельных фазах |
| `start_phase` | `phase_id` | Переводит фазу в `in_progress`, создаёт ветку `feature/phase_id` |
| `commit_phase` | `phase_id`, `commit_message` | `git add .` + `git commit` |
| `complete_phase` | `phase_id`, `summary`, `executor_name?`, `problems?` | Переводит в `completed`, merge в `main`, пишет лог в `AGENTS.md` |
| `fail_phase` | `phase_id`, `error_log` | Переводит в `failed`, hard reset, удаляет ветку |

---

## Установка

```bash
git clone <repo-url>
cd orchestrator-mcp
pip install -e ".[dev]"
```

Зависимости:
- Python ≥ 3.10
- System Git (доступный через `git` в PATH)

---

## Запуск

```bash
python -m src.server
```

Сервер запускается в режиме `stdio` (стандартный протокол MCP). Подключайтесь через любой MCP-клиент (например, `mcp-cli` или AI-ассистент с поддержкой MCP).

---

## Workflow разработки

```
1. get_project_state()
   └─► Сервер отвечает: доступна фаза "phase_2a"

2. start_phase("phase_2a")
   └─► Сервер создаёт ветку feature/phase_2a
   └─► Статус PLAN.md: phase_2a → in_progress

3. [Агент пишет код...]

4. commit_phase("phase_2a", "Added foo module")
   └─► git add . && git commit

5. [Агент продолжает или завершает...]

6. complete_phase("phase_2a", "Done", executor_name="...", problems="...")
   └─► Статус PLAN.md: phase_2a → completed
   └─► merge feature/phase_2a → main
   └─► Запись в AGENTS.md: дата, исполнитель, summary, хэш коммита, проблемы

7. get_project_state()
   └─► Сервер отвечает: доступны следующие фазы...
```

### Параллельные фазы

Если в `PLAN.md` две фазы помечены `parallel: true` и не пересекаются по `file_scope`, сервер сообщит о возможности параллельного выполнения. При попытке запустить фазу, чей `file_scope` пересекается с уже изменёнными файлами в параллельной ветке, сервер заблокирует запуск с сообщением:

> **Конфликт файлов. Выполняй фазы строго последовательно**

---

## Тестирование

```bash
pytest tests/ -v
```

Проект покрыт unit-тестами (`test_state_machine.py`, `test_git_operations.py`, `test_file_parser.py`) и интеграционными тестами (`test_server_integration.py`), которые создают временный Git-репозиторий для каждого теста.

---

## Лицензия

MIT