Aufgabe per MCP aktualisieren: Patch-Muster, Statusänderungen und Validierung

Entwicklerreferenz für das MCP-Tool update_task. So aktualisieren Sie Aufgabenfelder per Patch-Muster, handhaben Statusübergänge, validieren Änderungen und nutzen Bestätigungsmuster. Inkl. Beispiel-Tool-Aufrufe, natürliche Sprache, Grenzfälle und Fehlerbehebung.

Tool-Überblick

Zweck

Das Tool update_task aktualisiert ein oder mehrere Felder einer bestehenden Aufgabe. Nutzen Sie es, um Status zu ändern, Prioritäten anzupassen, Fälligkeitsdaten zu ändern oder andere Aufgabenfelder zu aktualisieren.

⚠️ Schreiboperation: Dieses Tool ändert Daten – immer Bestätigungsmuster verwenden und Änderungen vor dem Aufruf in der Vorschau anzeigen.

Eingabeparameter

Das Tool nutzt ein Patch-Muster – nur die zu ändernden Felder angeben. Außer task_id sind alle Felder optional.

Patch-Muster

Die Update-Operation nutzt ein Patch-Muster – es werden nur die zu ändernden Felder gesendet. Nicht enthaltene Felder bleiben unverändert.

Teilupdates:

• Einzelnes Feld: {"task_id": 123, "status": "done"} – aktualisiert nur den Status
• Mehrere Felder: {"task_id": 123, "status": "in_progress", "priority": "high"} – aktualisiert beides
• Feld leeren: {"task_id": 123, "due_date": null} – entfernt das Fälligkeitsdatum

Statusübergänge

Aufgaben können zwischen Status wechseln. Typische Abläufe:

Gültige Statuswerte:

• "open" – Aufgabe ist angelegt, aber nicht begonnen
• "in_progress" – Aufgabe wird bearbeitet
• "done" – Aufgabe ist abgeschlossen
• "blocked" – Aufgabe kann wegen Abhängigkeiten oder Problemen nicht fortgesetzt werden

Typische Status-Abläufe:

Arbeit beginnen: open → in_progress

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

Aufgabe abschließen: in_progress → done

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

Aufgabe blockieren: Beliebiger Status → blocked

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

Ausgabeformat

Das Tool liefert das aktualisierte Aufgabenobjekt mit allen Feldern (inkl. unveränderter):

{
  "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"
}

Sicherheitsprüfungen und Bestätigungsmuster

⚠️ Änderungen immer vor dem Update in der Vorschau anzeigen

KI darf Aufgaben nicht ohne Anzeige der geplanten Änderungen aktualisieren. Diese Muster verwenden:

• Zuerst lesen: get_task aufrufen, um den aktuellen Stand zu lesen
• Diff anzeigen: Pro Feld „Aktuell: X → Neu: Y“ anzeigen
• Bestätigungstoken: „CONFIRM“ verlangen, bevor update_task aufgerufen wird

Mehr zu sicheren Schreib-Workflows →

Sicheres Aufforderungsmuster

✅ Sicheres Aufforderungs-Template:

"Ich möchte die [Aufgabenname]-Aufgabe aktualisieren: [Änderungen].
Zeig mir zuerst die aktuellen Aufgabendetails, dann was sich ändern wird.
Nur aktualisieren, wenn ich CONFIRM tippe.
Wenn ich nicht bestätige, keine Änderungen vornehmen."

Beispiel-Tool-Aufrufe

Beispiel 1: Nur Status aktualisieren

Tool-Aufruf (JSON):

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

Rückgabe: Aufgabe mit auf „done“ aktualisiertem Status, alle anderen Felder unverändert

Beispiel 2: Mehrere Felder aktualisieren

Tool-Aufruf (JSON):

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

Rückgabe: Aufgabe mit aktualisiertem status, priority und due_date

Beispiel 3: Fälligkeitsdatum löschen

Tool-Aufruf (JSON):

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

Rückgabe: Aufgabe ohne Fälligkeitsdatum (auf null gesetzt)

Beispiele für natürliche Sprache

Sicheres Update mit Diff-Vorschau

Nutzeraufforderung:

"Aktualisiere den Status der Login-Feature-Aufgabe auf done. Zeig mir zuerst die aktuelle Aufgabe, dann was sich ändert, dann warte auf CONFIRM."

KI-Verhalten:

1. KI ruft get_task auf, um den aktuellen Stand zu lesen
2. KI zeigt: „Aktuell: Status = In Bearbeitung, Neu: Status = Erledigt“
3. KI wartet auf „CONFIRM“
4. KI ruft update_task erst nach Bestätigung auf
5. KI bestätigt, dass die Aufgabe aktualisiert wurde

Stapel-Status-Update

Nutzeraufforderung:

"Markiere alle Aufgaben im Q1-Projekt als erledigt. Zeig mir zuerst die Liste, dann warte auf CONFIRM ALL."

KI-Verhalten:

1. KI ruft list_tasks gefiltert nach Projekt auf
2. KI zeigt die Liste der zu aktualisierenden Aufgaben
3. KI wartet auf „CONFIRM ALL“
4. KI ruft update_task für jede Aufgabe auf

Typische Anwendungsfälle

• Fortschritts-Updates – Aufgabenstatus aktualisieren und Fortschrittskommentare hinzufügen
• Stapel-Titelbereinigung – Aufgabentitel über mehrere Aufgaben vereinheitlichen
• Aufgabenverwaltung – Prioritäten, Fälligkeitsdaten und Zuweisungen aktualisieren

Grenzfälle

Aufgabe nicht gefunden (404)

Situation: task_id existiert nicht

Antwort:

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

Umgang: Prüfen, ob die Aufgaben-ID korrekt ist

Ungültiger Statusübergang

Situation: Statuswert ist ungültig

Antwort:

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

Umgang: Nur gültige Statuswerte verwenden

Schreibgeschützte Felder

Situation: Es wird versucht, nicht änderbare Felder zu aktualisieren (z. B. id, created_at)

Antwort: Diese Felder werden ignoriert (kein Fehler, aber keine Änderung)

Umgang: Im Patch nur änderbare Felder angeben

Keine Änderungen

Situation: Die Update-Anfrage ändert kein Feld (alle Werte wie aktuell)

Antwort: Aufgabenobjekt unverändert zurückgegeben (kein Fehler)

Umgang: Das ist zulässig – das Tool liefert den aktuellen Stand

Fehlerbehebung

Validierungsfehler (400)

Symptom: 400 Bad Request mit Validierungsfehler

Ursachen:

• Ungültiger Status- oder Prioritätswert
• Ungültiges Datumsformat für due_date
• Ungültige project_id oder board_id
• Ungültige assignee_id

Lösung:

• Prüfen, ob alle Feldwerte gültig sind
• ISO-Datumsformat (YYYY-MM-DD) verwenden
• Vor der Nutzung prüfen, ob die IDs existieren

Validierungs-Fehlerbehebung →

Aufgabe nicht gefunden (404)

Symptom: 404 Not Found

Ursachen:

• Aufgaben-ID existiert nicht
• Aufgabe wurde gelöscht
• Ungültiges task_id-Format

Lösung:

• Prüfen, ob task_id korrekt ist
• Mit list_tasks oder get_task gültige IDs finden
• Prüfen, ob die Aufgabe noch existiert

Best Practices

update_task sicher nutzen

• ✅ Vor dem Update immer get_task aufrufen, um den aktuellen Stand zu lesen
• ✅ Diff-Vorschau vor dem Update anzeigen (Aktuell → Neu)
• ✅ Ausdrückliche Bestätigung verlangen (CONFIRM-Token)
• ✅ Patch-Muster nutzen – nur zu aktualisierende Felder angeben
• ✅ Vor dem Update prüfen, ob task_id korrekt ist
• ✅ Prüfen, ob Statusübergänge sinnvoll sind
• ✅ Prüfkommentare hinzufügen, die die Änderungen begründen
• ✅ Stapel-Updates vorsichtig handhaben (zuerst vollständige Liste zeigen)

Verwandte Tools

Oft zusammen verwendet mit:

• get_task – Aktuellen Aufgabenstand vor dem Update lesen
• list_tasks – Zu aktualisierende Aufgaben finden
• Least-Privilege Workflows – Sichere Schreib-Workflow-Muster