Task tracking (sessions, ETA, dashboard)

MCP Tracking

English summary. Local-first tracking of long-running tasks: an MCP server for Claude or Lyra, a small HTTP API on 127.0.0.1:8765 and a Textual terminal dashboard. Sessions have items, progress, logs and templates (download, machine, free, lyra_task, movie); pollers feed qBittorrent and Bazarr sessions automatically. Install: pip install . then mcp-tracking, mcp-tracking-api, mcp-tracking-ui. No cloud, no telemetry.

Serveur MCP de suivi en temps reel avec dashboard terminal. Permet a Claude/Lyra de tracker n'importe quelle operation longue ET alimente automatiquement les sessions depuis le media-server (qBittorrent, Bazarr, conversion DV).

---

Pourquoi c'est conçu pour des agents LLM

Un agent LLM (grand modèle de langage) qui lance une tâche longue (conversion, clone de VM, téléchargement) ne peut pas rester bloqué à la regarder, et il ne voit rien de ce qui se passe entre deux de ses tours. Ce serveur lui sert de mémoire de travail partagée :

• Un bus de progression commun. L'agent, les scripts shell et les pollers écrivent dans les mêmes sessions (outils MCP ou API HTTP locale sur 127.0.0.1:8765) : l'agent lance la tâche, rend la main, et relit l'état plus tard avec tracking_get.
• Des métriques calculées, pas devinées. Vitesse lissée sur 2 minutes, ETA, temps écoulé (metrics.py) : l'agent reçoit des chiffres au lieu d'extrapoler lui-même.
• Une tâche muette se voit. Une session running sans mise à jour depuis 10 minutes est marquée stale : l'agent distingue « encore en cours » de « processus mort ».
• Arrêter vise le bon processus. Une session peut porter le pid de son processus ; l'heure de démarrage relevée dans /proc évite de signaler un pid réutilisé par un autre programme. tracking_stop envoie SIGTERM et garde la session, tracking_kill envoie SIGKILL et la supprime.
• Pas de mise à jour perdue. L'état est un fichier JSON local, protégé par un verrou flock et réécrit de façon atomique (storage.py) : plusieurs agents et scripts peuvent écrire en même temps.
• Des gabarits par type de tâche (download, machine, movie, lyra_task, free) pour que chaque agent décrive son travail de la même façon.

Local-first et self-hosted : aucun cloud, aucune télémétrie, tout reste sur la machine (on-prem). Utilisé par Lyra, l'assistant vocal French-first, et par n'importe quel client MCP (Claude Code, Claude Desktop...).

Demo

Enregistree avec docs/demo/record.sh : server.py --test alimente quatre sessions simulees dans un repertoire d'etat temporaire (TRACKING_STATE_DIR), puis server.py --ui ouvre le dashboard dessus. Les sessions reelles ne sont pas touchees.

Sommaire

• Pourquoi c'est conçu pour des agents LLM
• Architecture
• Installation
• Services systemd
• Lancement
• Dashboard
• Integration media-server
• Outils MCP
• Templates
• Securite
• Ajouter un template

---

Architecture

MCP/tracking/

server.py -- Serveur MCP (outils Claude/Lyra) + point d'entree --ui / --test api.py -- API HTTP locale (127.0.0.1:8765) pour les scripts externes mutations.py -- Mutations d'une session, partagees par api.py ET server.py (horodatage items, historique, niveaux de log, auto-completion) metrics.py -- Metriques derivees (vitesse, ETA, ecoule, stale) -- logique pure, calculees a la lecture, jamais stockees storage.py -- Persistence JSON atomique + verrou fichier + cache mtime + purge TTL models.py -- Modeles pydantic (TrackingSession, TrackingItem, LogEntry, ProgressPoint) templates.py -- Templates builtin + templates utilisateur (JSON) ui.py -- Dashboard Textual (TUI temps reel) + modales stop/kill sim.py -- Simulations de demo (server.py --test) poller.py -- Daemon polling qBittorrent (10s) + Bazarr (60s) tracking-api.service -- Unite systemd (systeme) pour api.py tracking-poller.service -- Unite systemd (systeme) pour poller.py install.sh / deploy.sh -- Installation initiale / redeploiement des services Makefile -- make test | smoke | deploy | ui tests/ -- unitaires (storage, metrics) + integration/ (API HTTP reelle)

Fichiers d'etat et configuration

Un ancien tracking_state.json a cote du code est migre automatiquement au premier demarrage (copie, jamais supprime).

Variables d'environnement de retention :

Flux de donnees complet

Claude/Lyra (outils MCP)

| v server.py ─────────────────────────────────────────┐ | qBittorrent API (poll 10s) | | | Bazarr API (poll 60s) ──> poller.py ──> api.py ──> mutations.py ──> storage.py ──> ~/.local/state/tracking/tracking_state.json | | | dv_webhook_server.py | v | | ui.py v | (rafraichit chaque seconde) dv_convert.py ──────────────────────────────────────> (metriques temps reel ffmpeg/dovi_tool)

Le fichier d'etat est ecrit a chaque modification via ecriture atomique (os.replace) sous verrou fichier (tracking_state.lock). Tous les processus (MCP, API, poller, dashboard) partagent cet unique fichier ; chaque lecture verifie le mtime pour invalider son cache.

Toute mutation (HTTP ou MCP) passe par mutations.py, qui garantit le meme comportement sur les deux chemins : started_at / finished_at poses sur les items et la session, historique de progression (fenetre glissante de 40 points), niveaux de log info / warn / error, auto-completion quand tous les items sont termines.

Metriques derivees

GET /sessions et tracking_get renvoient un bloc metrics calcule a la volee par metrics.py :

---

Installation en une ligne

uvx mcp-tracking          # serveur MCP (stdio) ; avant publication : uvx --from git+https://github.com/amineutron/mcp-tracking mcp-tracking

uvx --from mcp-tracking mcp-tracking-api # API HTTP 127.0.0.1:8765 uvx --from mcp-tracking mcp-tracking-ui # tableau de bord terminal

Configuration Claude Desktop / Claude Code (mcpServers) :

{ "tracking": { "command": "uvx", "args": ["mcp-tracking"] } }

Installation

cd <dossier du dépôt>

Creer le venv et installer les dependances

uv venv .venv uv pip install "mcp[cli]>=1.0.0" "pydantic>=2.0" "textual>=0.80.0" "fastapi"

Le MCP est enregistre dans Claude Code (scope user) :

claude mcp list        # -> tracking: Connected

Pour reenregistrer :

claude mcp add tracking -s user -- \

/.venv/bin/python \ /server.py

---

Services systemd

Deux services tournent en permanence et se lancent au boot :

Installation initiale et redeploiement

cd <dossier du dépôt>

./install.sh # premiere fois : venv + services (demande sudo) sudo ./deploy.sh # apres chaque mise a jour du code : stop, unites, restart, verif make smoke # sante rapide

Les instances MCP server.py deja ouvertes par des sessions Claude Code ne sont pas redemarrees par deploy.sh : reconnecter tracking via /mcp dans ces sessions.

Commandes utiles

# Etat

systemctl status tracking-api.service tracking-poller.service

Logs en direct

journalctl -fu tracking-poller.service journalctl -fu tracking-api.service

Redemarrage

sudo systemctl restart tracking-api.service tracking-poller.service

Test API

curl http://127.0.0.1:8765/health curl http://127.0.0.1:8765/sessions

---

Lancement

Dashboard (raccourci wofi)

Cherche "MCP Tracking" dans wofi/launcher. Lance le dashboard dans Kitty.

Dashboard (terminal)

# Toutes les sessions

/.venv/bin/python \ /server.py --ui

Filtre direct au lancement

.venv/bin/python server.py --ui --filter download .venv/bin/python server.py --ui --filter movie .venv/bin/python server.py --ui --filter errors

Via outil MCP (depuis Claude/Lyra)

open_tracking_ui()                             # toutes les sessions

open_tracking_ui(filter_template="lyra_task") # vue Lyra uniquement open_tracking_ui(filter_template="errors") # erreurs uniquement

Mode test (demo)

.venv/bin/python server.py --test

Simule 4 sessions en parallele : download, machine (12 noeuds), free, movie (pipeline DV complet).

---

Dashboard

Layout d'une session

[TEMPLATE]  Nom de la session  id:xxxxxxxx  (status)

[=============> ] 54.2% 27100 MB / 50000 MB champ_extra1: valeur | champ_extra2: valeur

[ok] item-1 100.0 GB -- termine [>] item-2 frame: 94231 / 172800 (54.5%) speed: 3.2x [ ] item-3 -- [!] item-4 erreur detail

Logs Erreurs 14:32:01 Message log 1 [!] item-4 14:32:04 Message log 2 14:32:08 ECHEC: details 14:32:07 Message log 3 --

---

---

Icones items

Couleurs de session