Task tracking (sessions, ETA, dashboard)

MCP Tracking

英語の概要。 長時間実行タスクをローカル優先で追跡します。Claude または Lyra 向けの MCP サーバー、127.0.0.1:8765 上の小規模な HTTP API、Textual ターミナルダッシュボードを提供します。セッションには項目、進捗、ログ、テンプレート（download、machine、free、lyra_task、movie）があり、ポーラーが qBittorrent と Bazarr のセッションに自動でデータを送ります。インストール方法：pip install . の後、mcp-tracking、mcp-tracking-api、mcp-tracking-ui を実行します。クラウドもテレメトリーもありません。

リアルタイム追跡用の MCP サーバーとターミナルダッシュボードです。 Claude/Lyra があらゆる長時間処理を追跡でき、メディアサーバー（qBittorrent、Bazarr、DV 変換）からセッションに自動でデータを送ります。

---

LLM エージェント向けに設計されている理由

長時間タスク（変換、VM のクローン、ダウンロードなど）を開始する LLM（大規模言語モデル）エージェントは、その処理を見続けるために待機し続けることはできません。また、ターンとターンの間に何が起きているかも確認できません。このサーバーは、共有ワーキングメモリーとして機能します。

• 共通の進捗バス。 エージェント、シェルスクリプト、ポーラーは同じセッションに書き込みます（MCP ツールまたは 127.0.0.1:8765 上のローカル HTTP API）。エージェントはタスクを開始して制御を戻し、後で tracking_get を使って状態を読み直します。
• 推測ではなく、計算されたメトリクス。 2 分間で平滑化した速度、ETA、経過時間（metrics.py）を提供するため、エージェントは自分で推測せず、数値を受け取れます。
• 応答のないタスクを把握できます。 10 分間更新のない running セッションには stale のマークが付き、エージェントは「まだ実行中」と「プロセスが終了した」を区別できます。
• 停止対象のプロセスを正しく特定します。 セッションにはプロセスの pid を保持できます。/proc から取得した起動時刻を使うことで、別のプログラムに再利用された pid を誤って指すのを防ぎます。tracking_stop は SIGTERM を送信してセッションを保持し、tracking_kill は SIGKILL を送信してセッションを削除します。
• 更新を失いません。 状態はローカルの JSON ファイルに保存され、flock によるロックで保護され、アトミックに書き換えられます（storage.py）。複数のエージェントやスクリプトから同時に書き込めます。
• タスクの種類ごとのテンプレート（download、machine、movie、lyra_task、free）により、どのエージェントも同じ形式で作業内容を記述できます。

ローカル優先かつセルフホスト可能です。クラウドもテレメトリーもなく、すべてがマシン上（オンプレミス）に残ります。Lyra（フランス語優先の音声アシスタント）や、あらゆる MCP クライアント（Claude Code、Claude Desktop など）で利用されています。

デモ

docs/demo/record.sh を使って録画しています。server.py --test が一時的な状態ディレクトリ（TRACKING_STATE_DIR）に 4 つのシミュレーションセッションのデータを送り、その後 server.py --ui がその状態を使ってダッシュボードを開きます。実際のセッションには影響しません。

目次

• LLM エージェント向けに設計されている理由
• アーキテクチャ
• インストール
• systemd サービス
• 起動
• ダッシュボード
• メディアサーバーとの連携
• MCP ツール
• テンプレート
• セキュリティ
• テンプレートの追加

---

アーキテクチャ

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)

状態ファイルと設定

ファイル	場所	上書き設定
tracking_state.json	~/.local/state/tracking/	TRACKING_STATE_DIR
poller_state.json	~/.local/state/tracking/	TRACKING_STATE_DIR
templates.json（ユーザーテンプレート、任意）	~/.config/tracking/	TRACKING_TEMPLATES_FILE
credentials/*.cred（qBittorrent、Bazarr）	コードの隣、gitignore 対象	--

コードの隣にある古い tracking_state.json は、初回起動時に自動的に移行されます（コピーのみで、削除されません）。

保持期間の環境変数：

変数	デフォルト	役割
TRACKING_TTL_DAYS	7	完了／エラー／一時停止セッションを削除します
TRACKING_TTL_RUNNING_H	24	孤立した実行中セッション（更新がなくなったもの）を削除します

データフロー全体

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)

状態ファイルは、ファイルロック（tracking_state.lock）の下でアトミック書き込み（os.replace）により、変更のたびに書き込まれます。すべてのプロセス（MCP、API、ポーラー、ダッシュボード）がこの単一ファイルを共有し、読み込みのたびに mtime を確認してキャッシュを無効化します。

すべての変更（HTTP または MCP）は mutations.py を経由し、どちらの経路でも同じ動作を保証します。アイテムとセッションに started_at／finished_at を設定し、進捗履歴（直近 40 ポイントのスライディングウィンドウ）とログレベル info／warn／error を記録し、すべてのアイテムが完了すると自動的に完了扱いにします。

派生メトリクス

GET /sessions と tracking_get は、metrics.py がその場で計算する metrics ブロックを返します。

フィールド	意味
percent	進捗（100 を上限とします）
rate、rate_str	直近 120 秒間の速度（2.0 MB/s、30.0 u/min）
eta_seconds、eta_str	推定残り時間（実行中のセッションのみ）
elapsed_seconds、elapsed_str	created_at から finished_at または現在までの経過時間
idle_seconds、stale	stale は、10 分間更新のない実行中状態を示します（TUI に表示）

---

1 行でインストール

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

Claude Desktop／Claude Code の設定（mcpServers）：

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

インストール

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"

MCP は Claude Code にユーザースコープで登録されます。

claude mcp list        # -> tracking: Connected

再登録するには：

claude mcp add tracking -s user -- \
  <dossier du dépôt>/.venv/bin/python \
  <dossier du dépôt>/server.py

---

systemd サービス

2 つのサービスが常時稼働し、起動時に開始します。

サービス	役割	ポート
tracking-api.service	外部スクリプト用のローカル HTTP API	127.0.0.1:8765
tracking-poller.service	qBittorrent をポーリング（10 秒）＋ Bazarr（60 秒）	--

初回インストールと再デプロイ

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

Claude Code のセッションですでに開いている MCP インスタンス server.py は、deploy.sh では再起動されません。これらのセッションで /mcp から tracking に再接続してください。

便利なコマンド

# 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

---

起動

ダッシュボード（wofi のショートカット）

wofi／ランチャーで「MCP Tracking」を検索します。Kitty でダッシュボードを起動します。

ダッシュボード（ターミナル）

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

MCP ツール経由（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

テストモード（デモ）

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

4 つのセッションを並行してシミュレートします：ダウンロード、マシン（12 ノード）、フリー、ムービー（完全な DV パイプライン）。

---

ダッシュボード

セッションのレイアウト

[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               --
  --                                    --
  --                                    --

アイテムのアイコン

アイコン	ステータス	色
[ ]	pending	グレー
[>]	running	シアン
[ok]	done	緑
[!]	error	赤

セッションの色

色	ステータス
シアン	running
緑	done
赤	error
黄	paused

キーボードショートカット

キー	操作
f	次のフィルター（テンプレートに応じて動的に切り替わります）
e	エラーのみのフィルターを切り替えます
r	手動で更新します
s	セッションを正常に停止します（ID を入力）-> status paused
k	セッションを強制終了します（ID を入力）-> 削除
q	終了します
矢印キー / ホイール	スクロール

停止／強制終了モーダル

s または k を押すと、セッション ID を入力するフィールドを含むモーダルが開きます。

• s はセッションを paused にし、ログを追加します
• k はダッシュボードからセッションを完全に削除します
• Esc でキャンセルします

動的フィルタリング

フィルターの切り替え候補は、存在するセッションから自動的に構成されます：

all -> download -> free -> movie -> lyra_task -> errors -> all -> ...

• all は常に表示されます
• JSON 内に存在する各テンプレートが自動的に追加されます
• errors は、エラーのあるセッションが少なくとも 1 つある場合にのみ表示されます
• アクティブなフィルターはサブタイトルに表示されます：filtre: movie | 2/5 session(s)
• フィルター対象のテンプレートが JSON からなくなると、自動的に all に戻ります

---

media-server との統合

qBittorrent（自動）

ポーラーは 10 秒ごとに http://localhost:8080/api/v2/torrents/info を照会します。

• アクティブなトレントごとに、名前、サイズ、速度、ETA を含む [DOWNLOAD] セッションが作成されます
• トレントが完了するか、見つからなくなると、セッションは自動的に削除されます
• 認証情報：credentials/qbt-password.cred（systemd-creds --user で暗号化。media-server/scripts/secrets/rotate-secrets.sh によって生成されます）

Bazarr の字幕不足（自動）

ポーラーは 60 秒ごとに Bazarr API を照会します。

• 字幕がない FR のエピソード／映画すべてを、単一の [SUBTITLES] セッションに一覧表示します
• セッションのタイトルに合計数が表示されます：Sous-titres manquants (151)
• 字幕がない先頭 50 件のファイルが項目として一覧表示されます
• Bazarr API キー：credentials/bazarr-api-key.cred（同じ仕組み）。認証情報がない場合、該当するポーリングは無効になります。

Dolby Vision 変換（自動）

Radarr／Sonarr が DV Profile 4 または 7 の映画をインポートすると、dv-webhook.service によって開始されます。

フロー：

Radarr/Sonarr import
      |
      v
dv_webhook_server.py (port 8787)
      |-- cree session tracking via api.py
      |-- passe DV_TRACKING_SESSION_ID en env
      v
dv_convert.py
      |-- 6 etapes avec metriques temps reel
      |-- ffmpeg   : frame / speed / size / time (parse stderr)
      |-- dovi_tool: frames X/Y ou X% (parse stderr indicatif)
      v
session tracking completee ou en erreur

メトリクスとともに追跡される 6 つのステップ：

ステップ	ツール	表示されるメトリクス
1/6 HEVC 抽出	ffmpeg	frame / speed / size / time
2/6 BL／EL デマルチプレクス	dovi_tool	frames X/Y (%), bl: X GB, el: X GB
3/6 RPU 抽出 + P8 変換	dovi_tool	frames X/Y (%), RPU: X KB
4/6 BL への RPU P8 挿入	dovi_tool	frames X/Y (%), P8 HEVC: X GB
5/6 タイムスタンプ再構築	ffmpeg	frame / fps / size
6/6 最終 MKV リマックス	ffmpeg	frame / speed / size

全体の進捗バーは各ステップの実行中、継続的に進みます （各ステップの終了時に 1/6 ずつ進むのではありません）。

手動モード：

# Fichier unique
python <media-server>/scripts/dv_convert.py /chemin/film.mkv

# Scan dossier
python <media-server>/scripts/dv_convert.py --scan /mnt/media/media/movies

手動モードでは、process_file 内で追跡セッションが自動的に作成されます。

ローカル HTTP API（ポート 8765）

外部スクリプトからセッションを直接作成／変更できます：

# Creer une session
curl -X POST http://127.0.0.1:8765/sessions \
  -H "Content-Type: application/json" \
  -d '{"name":"Mon operation","template":"free","total":100,"unit":"%"}'
# -> {"id": "a1b2c3d4"}

# Mettre a jour
curl -X PUT http://127.0.0.1:8765/sessions/a1b2c3d4 \
  -H "Content-Type: application/json" \
  -d '{"processed":45,"log":"Etape 2/5 en cours","extra":{"phase":"etape 2"}}'

# Mettre a jour un item
curl -X PUT http://127.0.0.1:8765/sessions/a1b2c3d4 \
  -H "Content-Type: application/json" \
  -d '{"item":{"name":"mon-item","status":"done","note":"100 frames  speed: 2x"}}'

# Supprimer
curl -X DELETE http://127.0.0.1:8765/sessions/a1b2c3d4

# Lister
curl http://127.0.0.1:8765/sessions

完全な PUT 本文（すべてのフィールドは任意）：

{
  "processed": 45.0,
  "total":     100.0,
  "status":    "running",
  "extra":     {"phase": "etape 2"},
  "log":       "message de log",
  "item": {
    "name":      "nom-de-l-item",
    "status":    "running",
    "note":      "metriques ici",
    "processed": 50.0,
    "total":     100.0
  }
}

---

MCP ツール

tracking_create

Parametres:
  name      (str)          Nom de la session
  template  (str)          "download" | "machine" | "free" | "movie" | "lyra_task" |
                           "subtitles" | "series_episode" | "series_season" | template utilisateur
  total     (float)        Valeur totale
  unit      (str, opt)     Unite affichee (ex: " MB", " machines", "%")
  items     (list, opt)    Liste d'elements a suivre
  extra     (dict, opt)    Champs specifiques au template

Format items:
  [{"name": "fichier.iso", "total": 5100, "unit": " MB", "note": "info"}]

Retourne: ID de session + etat initial formate

tracking_update

Parametres:
  session_id    (str)          ID de la session
  processed     (float, opt)   Nouvelle valeur de progression
  message       (str, opt)     Message de log
  item_updates  (list, opt)    Mises a jour des items
  extra         (dict, opt)    Champs extra a merger

Format item_updates:
  [{"name": "item-1", "status": "done", "processed": 1200, "note": "detail"}]
  Status: "pending" | "running" | "done" | "error"

tracking_log

進捗を変更せずにログを追加します。

Parametres:
  session_id  (str)
  message     (str)

tracking_complete

100% で完了としてマークします。

Parametres:
  session_id  (str)
  message     (str, opt)

tracking_error

エラーとしてマークします（"ERREUR:" を自動でプレフィックスとして付加し、「エラー」列に表示します）。

Parametres:
  session_id  (str)
  message     (str)

tracking_stop

セッションを正常に停止します（status -> paused）。ダッシュボードには引き続き表示されます。

Parametres:
  session_id  (str)
  message     (str, opt)

tracking_kill

セッションを強制的に削除します。ダッシュボードからすぐに消えます。

Parametres:
  session_id  (str)

tracking_get

セッションの完全な状態を整形して返します。

tracking_list

Parametres:
  template  (str, opt)   Filtrer par template
  status    (str, opt)   Filtrer par statut ("running", "done", "error", "paused")

tracking_delete

セッションを削除します（tracking_kill と同等です）。

tracking_templates

テンプレートとそのフィールドの一覧を表示します。

open_tracking_ui

Kitty ターミナルでダッシュボードを開きます。

Parametres:
  filter_template  (str, opt)   Template a afficher au lancement

---

テンプレート

download

ファイルのダウンロードです。poller によって qBittorrent から自動的に登録されます。

Champs extra : speed, eta
Unite par defaut : MB

machine

マシンの操作（更新、クローン、スナップショット、デプロイ）です。 VM／クラスターの操作で Lyra に使用されます。

Champs extra : operation, target
Unite par defaut : machines

free

自由形式です。poller が不足している Bazarr の字幕に使用します。

Aucun champ extra impose, aucune unite par defaut.

lyra_task

Lyra の操作（VM のクローン、バックアップ、更新、スナップショット）です。

Champs extra : operation, target, phase, eta
Unite par defaut : %

movie

映画の完全なパイプラインです：ダウンロード -> Dolby Vision への変換。 Radarr／Sonarr が DV P4／P7 ファイルをインポートすると、dv_convert.py によって自動的に登録されます。

Champs extra : phase, quality, codec, audio, source, dv, speed, eta
Unite par defaut : %

Les 6 etapes DV trackees avec metriques temps reel :
  "1/6 extraction HEVC"
  "2/6 demux BL/EL"
  "3/6 extraction RPU + conv P8"
  "4/6 injection RPU P8 dans BL"
  "5/6 reconstruction timestamps"
  "6/6 remuxage MKV final"

---

セキュリティ

脅威モデル

デスクトップマシンに対する、現実的な攻撃者は 2 種類です：

1. ブラウザーで開いた Web ページ。 「localhost は境界ではありません」：Web ページは 127.0.0.1:8765 にリクエストを送信できます。保護がなければ、セッションの作成や削除、 そして特にプロセスへのシグナル送信を要求できてしまいます。
2. 別のローカルユーザー（または侵害されたサービス）による、状態の読み取りや API の操作の試みです。

対策

• api.py は 127.0.0.1:8765 のみでリッスンします。ネットワークからはアクセスできません。
• 書き込みにはローカルトークンが必須です：初回起動時に $XDG_RUNTIME_DIR/tracking/token に生成されます（権限は 0600 のため、他のユーザーには読み取れません）。POST、PUT、DELETE では Authorization: Bearer ... での提示が必要です。Web ページから読み取ることはできません。
• ブラウザーからのリクエストは拒否されます：Origin ヘッダーがあるリクエストは、トークンがあっても すべて 403 になります。
• Host ヘッダーを検証（ループバックのみ）し、書き込みには Content-Type: application/json を必須とします。
• シグナルの送信先は、サーバーに登録されたプロセスに限定されます：セッション作成時に、 サーバーは通知された pid が存在し、同じユーザーに属していることを確認してから、起動時刻を記録します。 /stop と /kill は、この指紋が変わった場合（別のプログラムによってプロセス番号が再利用された場合）や、 pid が登録されたことがない場合は、操作を拒否します。pid は PUT で変更できません。送信されたシグナルはすべて ログに記録されます。
• systemd サービスを強化：ProtectSystem=strict、書き込み可能な状態領域のみを除く ProtectHome=read-only、PrivateTmp、SystemCallFilter=@system-service、空の CapabilityBoundingSet=、UMask=0077 を設定しています。systemd-analyze security tracking-api.service で確認できます。
• 既知の制限：lyra-daemon は、マシン（サービス、VM、オーディオ）を操作するために sudo NOPASSWD を保持しています。これは tracking が付与するものではなく、強化は Lyra プロジェクトの範囲です。 このデーモンが存在する限り、このユーザーとしてコード実行を取得した攻撃者は、上記の保護とは無関係に この権限を利用できます。
• n8n は docker-compose.yml で 127.0.0.1:5678 に制限されています。
• dv_webhook_server.py は 0.0.0.0:8787 でリッスンします（Docker Webhook の受信に必要です）。マシンが外部に公開されている場合は、このポートをファイアウォールで保護してください。
• systemd サービスは NoNewPrivileges=true を設定して実行されます。
• コード内に平文のシークレットはありません：poller.py は $CREDENTIALS_DIRECTORY（user サービス）を読み取るか、credentials/*.cred を systemd-creds decrypt --user で復号します（system サービス）。デバッグ時は QBT_PASSWORD／BAZARR_KEY 環境変数にフォールバックします。

---

テンプレートの追加

1. templates.py を開き、TEMPLATES にエントリーを追加します：

"mon_template": {
    "description": "Description courte",
    "extra_fields": ["champ1", "champ2"],
    "default_unit": " unites",
    "example_extra": {"champ1": "valeur", "champ2": "valeur"},
},

2. 任意：sim.py に _sim_mon_template() シミュレーションを追加します。

テンプレートは、ほかに変更を加えなくてもすぐに利用できます。

コードを変更せずに、~/.config/tracking/templates.json でテンプレートを宣言することもできます （同じ構造で、キーはテンプレート名）。起動時に読み込まれます。

---

テスト

make test     # unitaires (storage, metrics) + integration (API HTTP reelle sur port ephemere)

conftest.py の autouse フィクスチャは、永続化先を tmp_path に変更します。そのため、テストが本番環境の状態に 触れることはありません。

Lyra エコシステムの一部

リポジトリ	役割
lyra	フランス語を第一言語とする音声アシスタント：デフォルトでローカル動作する音声 DevOps アシスタント（AGPL-3.0）。モデルを呼び出す前に、ルールによってくだけたフランス語を理解するため、0.5B のモデルで十分です
fedora-agents	MCP：KVM 仮想マシンとバックアップ
mcp-tracking	MCP＋API＋長時間実行タスクのダッシュボード
neutroncore	ホームラボの PWA ハブ
hue-mcp	Philips Hue MCP（ThomasRohde/hue-mcp のフォーク）
pylips-mcp	Philips TV MCP
denon-mcp	Denon アンプ MCP
catt-mcp	Chromecast および DLNA MCP