# 16_Kavita ## Kavita *Kavita is a fast, feature rich, cross platform reading server. Built with the goal of being a full solution for all your reading needs. Setup your own server and share your reading collection with your friends and family.* | | | |---|---| | **Image** | `jvmilazz0/kavita:latest` | | **Version** | latest | | **Etat** | Up (healthy) | | **Compose project** | kavita | | **Réseau** | kavita_default | | **URL** | https://kavita.juxjux.ovh | | **Source** | https://github.com/Kareadita/Kavita | ### Ports | Hote | Container | IP | |---|---|---| | 5471 | 5000/tcp | 0.0.0.0 | ### Volumes | Source (hote) | Destination | Type | Mode | |---|---|---|---| | `/home/debian/docker/kavita/config` | `/kavita/config` | bind | rw | | `/home/debian/livres` | `/manga` | bind | rw | --- ## Integration Claude Code — MCP | | | |---|---| | **Statut MCP** | MCP actif | | **Outils (prefix)** | `mcp__kavita__` | | **Configuration** | Script Python : `C:\Users\eliob\.claude\mcp_kavita.py` \| Auth : JWT via POST /api/Account/login | ### Outils opérationnels (confirmés 2026-06-25) - `get_libraries` — liste les 53 bibliothèques - `get_series` — liste les séries (filtre library_id non fonctionnel : retourne toutes les bibliothèques) - `get_series_detail` - `get_series_metadata` — retourne genres, auteurs, éditeur, résumé, année - `get_series_volumes` - `get_recently_added` - `get_on_deck` — séries en cours de lecture - `get_server_stats` - `search` — recherche full-text sur noms de séries, genres, fichiers, chapitres - `get_collections` — corrigé 2026-06-25 - `get_reading_lists` — corrigé 2026-06-25 - `get_want_to_read` — corrigé 2026-06-25 - `add_to_want_to_read` - `remove_from_want_to_read` - `get_user_stats` — corrigé 2026-06-25 - `get_reading_list` ### Ce que nous pouvons faire ensemble - Parcourir la bibliothèque par série, volume ou bibliothèque thématique - Rechercher un titre, auteur ou genre - Consulter les séries récemment ajoutées ou en cours de lecture - Gérer la liste "À lire" (ajout/suppression) - Consulter les collections et listes de lecture - Appeler l'API directement via PowerShell pour filtrer par genre (`/api/Series/all-v2`) --- ## REX — 2026-06-25 ### Statistiques bibliothèque | Stat | Valeur | |---|---| | Bibliothèques | 53 (toutes de type Book/epub+PDF) | | Séries | 2 976 | | Fichiers | 5 519 | | Volumes | 1 173 | | Taille totale | ~79 Go | | Auteurs/contributeurs indexés | 3 475 | | Genres indexés | 6 990 | | Tags | 0 | ### Étiquettes Calibre → genres Kavita Les étiquettes appliquées via Calibre sont **visibles dans Kavita sous le champ `genres`**, pas `tags` (qui reste toujours vide, `totalTags: 0`). Mécanisme : Calibre écrit ses étiquettes dans `` du fichier epub lors du writeback → Kavita lit ce champ et le mappe en genres. **Exemple confirmé** — "Il faut s'adapter" (Barbara Stiegler, lib. Actualités, ID série 4210) : - genres : `Actualités`, `Philosophie`, `Politique`, `2020-2025` **Conditions pour que ça fonctionne :** - Le fichier epub doit avoir été re-sauvegardé depuis Calibre après ajout des étiquettes (Préférences > Sauvegarde des métadonnées → writeback activé) - La bibliothèque Kavita doit avoir `enableMetadata: true` (c'est le cas pour Actualités) - Les PDFs ne portent généralement pas les métadonnées Calibre → genres vides La bibliothèque **Actualités** (ID 63) est entièrement étiquetée et correctement indexée. ### Lecture du contenu Le MCP **ne permet pas de lire le contenu** des livres — uniquement les métadonnées. Kavita expose des endpoints de lecture (`/api/Reader/image`, `/api/Reader/epub-file`) mais non implémentés dans le MCP. Pour les epub, la lecture via appel API direct + parsing HTML serait techniquement faisable au cas par cas. ### Corrections endpoints MCP (2026-06-25) 4 outils retournaient 404 suite à des changements d'API dans la version Kavita en production. Corrections appliquées dans `mcp_kavita.py` : | Outil | Ancien endpoint (404) | Nouveau endpoint (200) | |---|---|---| | `get_collections` | `GET /api/Collection/list` | `GET /api/Collection` | | `get_reading_lists` | `GET /api/ReadingList/lists?includePromoted=true` | `POST /api/ReadingList/lists` body `{}` | | `get_want_to_read` | `POST /api/Want-To-Read/get-list` | `POST /api/Want-To-Read` | | `get_user_stats` | `GET /api/Stats/user/0/read` | `GET /api/Stats/user-stats?userId={id}` | Note : le `userId` est désormais extrait dynamiquement du payload de login (`data["id"]`) et stocké dans `_user_id`. ### Limitations MCP identifiées - Le paramètre `library_id` de `get_series` ne filtre pas : retourne toutes les bibliothèques triées alphabétiquement - Pour filtrer par genre, utiliser l'API directe : `POST /api/Series/all-v2` avec filtre JSON (hors MCP, via PowerShell) ### Problème pipeline Calibre → Kavita — À résoudre **Constat (2026-06-25)** : les fichiers enrichis par Calibre (avec étiquettes + métadonnées ISBN) ne remplacent pas les fichiers originaux dans le dossier Kavita. Kavita lit depuis le dossier source original (`/manga` = kDrive `Sync_NAS-Maison/Foxy`) qui contient les fichiers **sans métadonnées**. Calibre, en mode par défaut, **copie** les fichiers dans sa propre arborescence et les enrichit là — les originaux restent intacts. Résultat : 98% des fichiers ont des métadonnées correctes dans Calibre, mais Kavita voit des genres vides. **Questions ouvertes à clarifier :** - Où est la bibliothèque Calibre (Windows, NAS Maison, autre) ? - Le dossier source Kavita et le dossier d'import Calibre sont-ils le même, ou séparés ? - Calibre est-il en mode copie (défaut) ou lien vers fichier original ? **Piste de solution** : exporter les fichiers enrichis depuis la bibliothèque Calibre vers le dossier source Kavita (via "Enregistrer sur le disque" dans Calibre), en remplacement des originaux. Peut s'automatiser. À instruire.