Обновление задачи через MCP: паттерны патчей, изменение статуса и валидация

Справочник разработчика по MCP-инструменту update_task. Узнайте, как обновлять поля задачи с помощью паттернов патчей, обрабатывать переходы статусов, валидировать изменения и использовать паттерны подтверждения. Включает примеры вызовов инструмента, промпты на естественном языке, краевые случаи и устранение неполадок.

Обзор инструмента

Назначение

Инструмент update_task обновляет одно или несколько полей существующей задачи. Используйте этот инструмент, чтобы изменить статус, обновить приоритеты, изменить сроки выполнения или обновить любое другое поле задачи.

⚠️ Операция записи: этот инструмент изменяет данные — всегда используйте паттерны подтверждения и предпросмотр изменений перед его вызовом.

Входные параметры

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

Паттерны патчей

Операция обновления использует паттерн патча — вы отправляете только те поля, которые хотите изменить. Поля, не включённые в запрос, остаются без изменений.

Частичные обновления:

• Одно поле: {"task_id": 123, "status": "done"} — обновляет только статус
• Несколько полей: {"task_id": 123, "status": "in_progress", "priority": "high"} — обновляет оба
• Очистка поля: {"task_id": 123, "due_date": null} — удаляет срок выполнения

Переходы статусов

Задачи могут переходить между статусами. Типичные рабочие процессы:

Допустимые значения статуса:

• "open" — задача создана, но не начата
• "in_progress" — задача активно выполняется
• "done" — задача завершена
• "blocked" — задача не может продолжаться из-за зависимостей или проблем

Типичные рабочие процессы статусов:

Начало работы: open → in_progress

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "status": "in_progress"
  }
}

Завершение задачи: in_progress → done

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "status": "done"
  }
}

Блокировка задачи: любой статус → blocked

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "status": "blocked"
  }
}

Формат вывода

Инструмент возвращает обновлённый объект задачи со всеми полями (включая неизменённые):

{
  "id": 123,
  "title": "Implement login feature",
  "description": "Add user authentication...",
  "status": "in_progress",
  "priority": "high",
  "due_date": "2026-02-28",
  "project_id": 456,
  "board_id": 789,
  "assignee_id": 101,
  "updated_at": "2026-03-05T14:30:00Z"
}

Проверки безопасности и паттерны подтверждения

⚠️ Всегда просматривайте изменения перед обновлением

Никогда не позволяйте ИИ обновлять задачи, не показывая, что именно изменится. Используйте эти паттерны:

• Сначала чтение: вызовите get_task, чтобы прочитать текущее состояние
• Показ различий: отобразите «Текущее: X → Новое: Y» для каждого поля
• Токен подтверждения: требуйте «CONFIRM» перед вызовом update_task

Узнать больше о безопасных рабочих процессах записи →

Паттерн безопасного промпта

✅ Шаблон безопасного промпта:

"I want to update the [task name] task: [changes]. 
First, show me the current task details, then show me what will change. 
Only update if I type CONFIRM. 
If I don't confirm, don't make any changes."

Примеры вызовов инструмента

Пример 1: обновление только статуса

Вызов инструмента (JSON):

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "status": "done"
  }
}

Возвращает: задачу со статусом, обновлённым до "done", все остальные поля без изменений

Пример 2: обновление нескольких полей

Вызов инструмента (JSON):

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "status": "in_progress",
    "priority": "high",
    "due_date": "2026-03-10"
  }
}

Возвращает: задачу с обновлёнными status, priority и due_date

Пример 3: очистка срока выполнения

Вызов инструмента (JSON):

{
  "tool": "update_task",
  "arguments": {
    "task_id": 123,
    "due_date": null
  }
}

Возвращает: задачу с удалённым сроком выполнения (установлен в null)

Примеры промптов на естественном языке

Безопасное обновление с предпросмотром различий

Промпт пользователя:

"Update the login feature task status to done. First show me the current task, then show what will change, then wait for CONFIRM."

Поведение ИИ:

1. ИИ вызывает get_task, чтобы прочитать текущее состояние
2. ИИ показывает: "Current: Status = In Progress, New: Status = Done"
3. ИИ ждёт «CONFIRM»
4. ИИ вызывает update_task только после подтверждения
5. ИИ подтверждает, что задача была обновлена

Пакетное обновление статуса

Промпт пользователя:

"Mark all tasks in the Q1 project as done. Show me the list first, then wait for CONFIRM ALL."

Поведение ИИ:

1. ИИ вызывает list_tasks с фильтром по проекту
2. ИИ показывает список задач, которые будут обновлены
3. ИИ ждёт «CONFIRM ALL»
4. ИИ вызывает update_task для каждой задачи

Типичные сценарии использования

• Обновления прогресса — обновляйте статус задачи и добавляйте комментарии о прогрессе
• Пакетная очистка заголовков — стандартизируйте заголовки задач по нескольким задачам
• Управление задачами — обновляйте приоритеты, сроки выполнения и назначения

Краевые случаи

Задача не найдена (404)

Ситуация: task_id не существует

Ответ:

{
  "error": "not_found",
  "message": "Task with ID 123 not found"
}

Обработка: убедитесь, что ID задачи корректен

Некорректный переход статуса

Ситуация: значение статуса недопустимо

Ответ:

{
  "error": "validation_error",
  "message": "Invalid status. Must be: open, in_progress, done, or blocked",
  "field": "status"
}

Обработка: используйте только допустимые значения статуса

Поля только для чтения

Ситуация: попытка обновить поля, которые нельзя изменить (например, id, created_at)

Ответ: эти поля игнорируются (без ошибки, но без изменений)

Обработка: включайте в патч только обновляемые поля

Нет изменений

Ситуация: запрос на обновление не меняет ни одного поля (все значения совпадают с текущими)

Ответ: объект задачи возвращается без изменений (без ошибки)

Обработка: это допустимо — инструмент возвращает текущее состояние

Устранение неполадок

Ошибки валидации (400)

Симптом: 400 Bad Request с ошибкой валидации

Причины:

• Некорректное значение status или priority
• Некорректный формат даты для due_date
• Некорректный project_id или board_id
• Некорректный assignee_id

Решение:

• Убедитесь, что все значения полей допустимы
• Используйте формат даты ISO (YYYY-MM-DD)
• Проверьте существование ID перед их использованием

Читать об устранении ошибок валидации →

Задача не найдена (404)

Симптом: ошибка 404 Not Found

Причины:

• ID задачи не существует
• Задача была удалена
• Некорректный формат task_id

Решение:

• Убедитесь, что task_id корректен
• Используйте list_tasks или get_task, чтобы найти допустимые ID
• Проверьте, существует ли ещё задача

Лучшие практики

Безопасное использование update_task

• ✅ Всегда сначала вызывайте get_task, чтобы прочитать текущее состояние
• ✅ Показывайте предпросмотр различий перед обновлением (Текущее → Новое)
• ✅ Требуйте явного подтверждения (токен CONFIRM)
• ✅ Используйте паттерн патча — включайте только обновляемые поля
• ✅ Убедитесь, что task_id корректен перед обновлением
• ✅ Проверяйте, что переходы статусов имеют смысл
• ✅ Добавляйте аудиторские комментарии, объясняющие причину изменений
• ✅ Осторожно выполняйте пакетные обновления (сначала показывайте полный список)

Связанные инструменты

Часто используются вместе с:

• get_task — прочитайте текущее состояние задачи перед обновлением
• list_tasks — найдите задачи для обновления
• Рабочие процессы с минимальными привилегиями — паттерны безопасной записи