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 -- \
  <dossier du dépôt>/.venv/bin/python \
  <dossier du dépôt>/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