Zeiterfassung starten per MCP: Arbeitssitzungen mit Aufgaben verknüpfen

Entwicklerreferenz für das MCP-Tool start_time_tracking. So starten Sie einen Timer für eine Aufgabe, verhindern mehrere Timer und nutzen Bestätigungsmuster. Inkl. Sicherheitsprüfungen, Beispiel-Tool-Aufrufen, natürlicher Sprache, Grenzfällen und Fehlerbehebung.

Tool-Überblick

Zweck

Das Tool start_time_tracking startet einen Timer für eine bestimmte Aufgabe. Nutzen Sie es, um verbrachte Zeit zu erfassen, Codier-Sitzungen mit Aufgaben zu verknüpfen oder Fokus-Sitzungen zu beginnen. Pro Arbeitsbereich kann nur ein Timer gleichzeitig laufen.

⚠️ Schreib-Operation: Dieses Tool ändert Daten – immer Bestätigungsmuster verwenden und vor dem Aufruf auf bestehende Timer prüfen.

Eingabeparameter

Das Tool benötigt eine Aufgaben-ID, um die Erfassung zu starten.

Ausgabeformat

Das Tool liefert das Erfassungsstatus-Objekt:

{
  "task_id": 123,
  "task_title": "Implement login feature",
  "started_at": "2026-03-19T10:30:00Z",
  "is_running": true
}

Sicherheitsprüfungen und Bestätigungsmuster

⚠️ Immer zuerst auf bestehenden Timer prüfen

KI niemals einen Timer starten lassen, ohne auf bestehende Timer zu prüfen. Diese Muster nutzen:

• Zuerst Status prüfen: get_tracking_status aufrufen, um zu prüfen, ob bereits ein Timer läuft
• Bestehenden Timer stoppen: Wenn ein Timer läuft, zuerst stoppen oder Nutzer um Bestätigung bitten
• Aufgabe bestätigen: Aufgabentitel und -ID anzeigen, bevor der Timer gestartet wird
• Bestätigungstoken: "CONFIRM" verlangen, bevor start_time_tracking aufgerufen wird

Mehr zu sicheren Schreib-Workflows →

Sicheres Aufforderungsmuster

✅ Sicheres Aufforderungs-Template:

"Ich möchte die Zeiterfassung für Aufgabe #123 starten. 
Prüfe zuerst, ob bereits ein Timer läuft. 
Wenn ja, frage mich, ob ich ihn zuerst stoppen soll. 
Dann zeig mir den Aufgabentitel und warte auf CONFIRM, bevor du den Timer startest. 
Wenn ich nicht CONFIRM tippe, starte nichts."

Beispiel-Tool-Aufrufe

Beispiel 1: Timer starten

Tool-Aufruf (JSON):

{
  "tool": "start_time_tracking",
  "arguments": {
    "task_id": 123
  }
}

Rückgabe: Erfassungsstatus mit task_id, task_title, started_at und is_running=true

Beispiele für natürliche Sprache

Sicheres Timer-Start mit Statusprüfung

Nutzeraufforderung:

"Starte die Zeiterfassung für die Login-Feature-Aufgabe. Prüfe zuerst, ob ein Timer läuft."

KI-Verhalten:

1. KI ruft get_tracking_status auf, um auf bestehenden Timer zu prüfen
2. Wenn Timer existiert, warnt KI: "Timer läuft bereits für Aufgabe X. Zuerst stoppen?"
3. Wenn kein Timer, findet KI die Aufgabe mit list_tasks oder get_task
4. KI zeigt: "Timer starten für: Login Feature (Aufgabe #123)"
5. KI wartet auf "CONFIRM"
6. KI ruft start_time_tracking erst nach Bestätigung auf

Arbeitssitzung starten

Nutzeraufforderung:

"Ich fange mit Aufgabe #456 an. Starte den Timer, prüfe aber zuerst auf bestehende Timer."

KI-Verhalten:

1. KI prüft get_tracking_status
2. KI verifiziert mit get_task, dass Aufgabe #456 existiert
3. KI zeigt Vorschau und bittet um Bestätigung
4. Nach Bestätigung startet KI den Timer

Typische Anwendungsfälle

• Zeiterfassung-Grundlagen – Timer starten, wenn die Arbeit an einer Aufgabe beginnt
• Editor-Workflow – Codier-Sitzungen über Timer mit Aufgaben verknüpfen
• Täglicher Fokus – Timer für die Tages-Prioritätsaufgabe starten
• Zuerst Status prüfen – Immer auf bestehende Timer prüfen, bevor gestartet wird

Grenzfälle

Timer läuft bereits

Situation: Ein Timer läuft bereits für eine andere Aufgabe

Antwort:

{
  "error": "timer_already_running",
  "message": "Timer is already running for task 456",
  "current_task_id": 456,
  "current_task_title": "Previous Task",
  "started_at": "2026-03-19T09:00:00Z"
}

Umgang: Zuerst den bestehenden Timer mit stop_time_tracking stoppen, dann neuen Timer starten

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

Berechtigung verweigert (403)

Situation: Aufgabe existiert, aber Sie haben keine Berechtigung zur Zeiterfassung

Antwort:

{
  "error": "forbidden",
  "message": "You don't have permission to track time for this task"
}

Umgang: Aufgabenberechtigungen in Corcava prüfen

403-Fehlerbehebungsanleitung →

Fehlerbehebung

Timer läuft bereits

Symptom: Fehler, dass bereits ein Timer läuft

Ursachen:

• Ein anderer Timer ist für eine andere Aufgabe aktiv
• Vorheriger Timer wurde nicht gestoppt

Lösung:

• get_tracking_status aufrufen, um den aktuellen Timer zu sehen
• stop_time_tracking aufrufen, um den bestehenden Timer zu stoppen
• Anschließend start_time_tracking für die neue Aufgabe aufrufen

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

start_time_tracking sicher nutzen

• ✅ Immer zuerst get_tracking_status aufrufen, um auf bestehende Timer zu prüfen
• ✅ Bestehenden Timer stoppen, bevor ein neuer gestartet wird (oder Nutzer bestätigen lassen)
• ✅ Mit get_task prüfen, ob die Aufgabe existiert, bevor der Timer gestartet wird
• ✅ Aufgabentitel und -ID dem Nutzer anzeigen, bevor gestartet wird
• ✅ Ausdrückliche Bestätigung verlangen (CONFIRM-Token)
• ✅ stop_time_tracking nutzen beim Wechsel der Aufgabe oder beim Beenden der Arbeit

Verwandte Tools

Oft zusammen verwendet mit:

• get_tracking_status – Vor dem Start auf bestehende Timer prüfen
• stop_time_tracking – Timer stoppen beim Wechsel der Aufgabe oder Beenden der Arbeit
• get_task – Prüfen, ob Aufgabe existiert, bevor Timer gestartet wird
• Least-Privilege Workflows – Sichere Schreib-Workflow-Muster