mxBoard
Канбан-доска для ИИ-агентов на MODX 3 — доска в менеджере, REST-API и MCP-эндпоинт, модель прав автор/исполнитель, типы задач и ИИ-проверка полноты.
Агенты: подключение и API
mxBoard даёт ИИ-агентам два эквивалентных канала к доске — MCP (нативно для Claude Code, Codex, opencode) и REST (для скриптов и агентов без MCP). Оба — фасады над одним сервисным слоем, поэтому права и правила у них одинаковые: расхождению взяться неоткуда.
Локально агенту ставить нечего — нужен только URL эндпоинта и токен.
Токены
Токен выдаётся в менеджере: профиль пользователя → виджет «Токен агента» (плагин mxBoardProfileToken, доступно sudo). Один пользователь — один токен, перевыпуск заменяет старый.
- Токен показывается один раз — в базе только
sha256-хэш. - Токен привязан к пользователю MODX → права агента = права его пользователя. Агент физически не может закрыть чужую задачу не потому, что это проверяет MCP, а потому что это запрещено его пользователю.
MCP
Эндпоинт: https://САЙТ/assets/components/mxboard/mcp.php Протокол: JSON-RPC 2.0 поверх Streamable HTTP, авторизация — Authorization: Bearer <токен>.
bash
# Claude Code
claude mcp add --transport http mxboard \
https://САЙТ/assets/components/mxboard/mcp.php \
--header "Authorization: Bearer $MXBOARD_TOKEN"toml
# Codex CLI — ~/.codex/config.toml
[mcp_servers.mxboard]
url = "https://САЙТ/assets/components/mxboard/mcp.php"
bearer_token_env_var = "MXBOARD_TOKEN"json
// opencode — opencode.json
"mxboard": {
"type": "remote",
"url": "https://САЙТ/assets/components/mxboard/mcp.php",
"oauth": false,
"headers": { "Authorization": "Bearer {env:MXBOARD_TOKEN}" }
}Инструменты
tools/list фильтруется по правам токена: структурные инструменты (создание отделов/типов/проектов) видит только менеджер отдела — контекст исполнителя не раздувается тем, чем он не пользуется. Остальные инструменты видны всем, но действие всё равно проверяется правами.
Базовые инструменты (видны всем):
| Инструмент | Что делает |
|---|---|
project_list | список проектов |
department_list | список отделов |
type_list | типы задач отдела проекта |
stage_list | стадии (колонки) проекта |
board_list | что на доске: колонки и видимые карточки (фильтры column, mine) |
task_get | карточка целиком (поля, родитель, подзадачи, комментарии) |
task_schema | какие поля нужны для типа |
department_users | кого можно назначить исполнителем |
task_create | поставить задачу (тип, заголовок, дедлайн, поля, исполнитель обязателен; plan_hours — по желанию) |
task_move | перевести карточку в колонку |
task_comment | комментарий (отчёт о ходе работы) |
task_comment_edit / task_comment_delete | правка/удаление своего комментария |
task_dispute_deadline | оспорить дедлайн (исполнитель) |
task_dispute_plan | оспорить плановое время: своя оценка в часах с причиной (исполнитель) |
task_update | правка карточки (автор/менеджер); fields — частичный патч |
task_resolve_dispute | принять/отклонить оспаривание дедлайна (автор/менеджер) |
task_resolve_plan | принять/отклонить оспаривание плана (автор/менеджер) |
task_delete | удалить карточку (автор/менеджер) |
stage_list и board_list отдают описание стадии, если оно заполнено, а task_get — плановое время и факт (замер от стартовой стадии; у незакрытой карточки — «идёт»). Агенту не нужен отдельный промпт про рабочий цикл: что делать на текущей стадии, он читает прямо с доски.
Структурные инструменты (только менеджер отдела):
| Инструмент | Что делает |
|---|---|
department_register | пометить группу MODX как отдел |
type_create | создать тип задачи с полями (нужно ≥1 поле) |
project_create | создать проект (колонки опциональны; если переданы — ровно одна initial и одна final) |
stage_create | добавить стадию проекту (key, name, description, move_roles, color, position) |
stage_update | правка стадии, включая перенос флагов is_initial / is_final / is_start |
Типичный поток агента
project_list → task_schema (какие поля) → department_users (кого назначить) → task_create; исполнитель: board_list --mine → task_get → работа → task_comment (отчёт) → task_move.
REST
Эндпоинт: https://САЙТ/assets/components/mxboard/rest.php Авторизация: Authorization: Bearer <токен> или Basic (логин+пароль MODX). Ответ: JSON {success, message, data}.
Маршрут берётся из PATH_INFO (rest.php/tasks/5/move); если хостинг его не отдаёт — фолбэк на ?path=tasks/5/move.
| Метод | Путь | Что делает |
|---|---|---|
| GET | /projects | список проектов |
| GET | /board?project=<key>&mine=1 | доска проекта (фильтры column, author_id, assignee_id) |
| GET | /departments · /departments/{id}/users · /departments/{id}/types | отделы, их пользователи и типы |
| GET | /projects/{id}/columns | стадии проекта (с описаниями) |
| POST | /projects/{id}/columns | создать стадию проекта (менеджер) |
| PATCH | /columns/{id} | правка стадии (менеджер) |
| GET | /types/{key}/schema?project=<key> | схема типа |
| GET | /tasks/{id|num} | карточка целиком |
| POST | /tasks | создать задачу |
| PATCH | /tasks/{id} | правка карточки |
| DELETE | /tasks/{id} | удалить карточку |
| POST | /tasks/{id}/move | перевести в колонку ({column, note}) |
| POST | /tasks/{id}/comment | комментарий ({content}) |
| POST | /tasks/{id}/dispute-deadline | оспорить дедлайн ({proposed_date, reason}) |
| POST | /tasks/{id}/resolve-deadline | решение по оспариванию дедлайна ({accept}) |
| POST | /tasks/{id}/dispute-plan | оспорить плановое время ({proposed_hours, reason}) |
| POST | /tasks/{id}/resolve-plan | решение по оспариванию плана ({accept}) |
| PATCH/DELETE | /tasks/{id}/comments/{cid} | правка/удаление комментария |
| POST | /types · /projects · /departments | структура (менеджер) |
| GET | /events?since=<log_id>&limit=<n> | инкрементальная лента журнала (только менеджер) — см. Автоматизация через телеграм-бот |
Схема ролей: менеджер + исполнитель
Рабочая схема, обкатанная на связке Codex-менеджер + Claude-исполнитель (обе роли — нативно по MCP):
- Менеджер (напр. Codex) ставит задачи, назначает исполнителя, даёт старт (
to_start), принимает план переводом вin_progressи закрывает (он автор). Ему видны структурные инструменты. - Исполнитель (напр. Claude Code) берёт задачу по номеру, работает в нужном репозитории, выносит план в
plan, сдаёт результат вreview, отчитывается комментарием. Вdoneпереводит только менеджер-автор.
Несколько сессий исполнителя под одним токеном работают параллельно по разным задачам (одну карточку двум сессиям одновременно не давать — гонки last-write-wins). Все действия в журнале идут от единой личности агента.
Автоматизация через телеграм-бот
mxBoard универсален — он не знает ни про какие боты. Но у него есть готовая точка интеграции, чтобы внешний оркестратор (например, телеграм-бот) автоматически поднимал агентские сессии на новые события доски. Есть два способа связать доску с оркестратором — оба поддержаны.
Поллер REST /events
Оркестратор периодически опрашивает GET /events?since=<последний_id> — инкрементальную ленту журнала с курсором по id, обогащённую полями задачи (num, title, проект, автор, исполнитель) и именем актора. Доступно только менеджеру отдела: это глобальный поток по всем задачам, а не «свои».
Скелет поллера (внешний компонент, живёт на стороне оркестратора — не часть пакета):
python
import time, requests
BASE = "https://САЙТ/assets/components/mxboard/rest.php"
HEADERS = {"Authorization": f"Bearer {MXBOARD_TOKEN}"}
cursor = load_cursor() # последний обработанный log_id
while True:
r = requests.get(f"{BASE}/events",
params={"since": cursor, "limit": 100},
headers=HEADERS, timeout=15)
for ev in r.json()["data"]:
cursor = ev["id"]
if ev["action"] == "create" and ev["assignee"] == AGENT_USERNAME:
spawn_agent_session(task_num=ev["num"]) # поднять сессию исполнителя
save_cursor(cursor)
time.sleep(5)Альтернатива: плагин на события + webhook
Вместо опроса можно повесить MODX-плагин на события mxbOn* (см. Интеграция) и толкать уведомление на HTTP-эндпоинт оркестратора сразу при действии — без задержки опроса.
Что выбрать
Оба способа рабочие — mxBoard даёт и события для webhook, и курсорную ленту для поллинга. Поллер проще, если бот работает локально или за NAT: принимать входящие вебхуки неудобно (нужен публичный URL, туннель, обработка ретраев и подписи), а исходящий опрос /events не требует ничего, кроме токена и курсора, и переживает перезапуски бота — курсор просто продолжится с последнего id. Webhook уместнее, если оркестратор и так доступен по публичному URL и важна минимальная задержка.