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

Related MCP server: morpheus-mcp

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

Каждый файл содержит 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-инструменты

Установка

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