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, удаляет ветку

---

Установка

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

Зависимости:

• Python ≥ 3.10
• System Git (доступный через git в PATH)

---

Запуск

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 пересекается с уже изменёнными файлами в параллельной ветке, сервер заблокирует запуск с сообщением:

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

---

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

pytest tests/ -v

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

---

Лицензия

MIT