toonify-mcp 0.2.3 → 0.3.1

package/README.fr.md

@@ -0,0 +1,270 @@
+# 🎯 Toonify MCP
+
+**[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [Español](README.es.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [한국어](README.ko.md) | [Русский](README.ru.md) | [Português](README.pt.md) | [Tiếng Việt](README.vi.md) | [Bahasa Indonesia](README.id.md)**
+
+Serveur MCP + Plugin Claude Code offrant une optimisation automatique des tokens pour les données structurées.
+Réduit l'utilisation des tokens de l'API Claude de **30 à 65 % selon la structure des données** grâce à la conversion transparente au format TOON, avec des économies typiques de **50 à 55 %** pour les données structurées.
+
+## Nouveautés de la version 0.3.0
+
+✨ **Optimisation multilingue des tokens !**
+- ✅ Comptage précis des tokens pour plus de 15 langues (chinois, japonais, coréen, espagnol, arabe, etc.)
+- ✅ Multiplicateurs de tokens adaptés aux langues (2x pour le chinois, 2,5x pour le japonais, 3x pour l'arabe)
+- ✅ Support des textes multilingues avec détection automatique
+- ✅ Précision d'optimisation améliorée basée sur des benchmarks réels
+- ✅ Revendications d'économies de tokens basées sur des données (plage de 30 à 65 %, typiquement 50 à 55 %)
+
+## Fonctionnalités
+
+- **Réduction de 30 à 65 % des tokens** (typiquement 50 à 55 %) pour les données JSON, CSV, YAML
+- **Support multilingue** - Comptage précis des tokens pour plus de 15 langues
+- **Entièrement automatique** - Le hook PostToolUse intercepte les résultats des outils
+- **Zéro configuration** - Fonctionne immédiatement avec des paramètres par défaut sensés
+- **Mode double** - Fonctionne comme Plugin (auto) ou serveur MCP (manuel)
+- **Métriques intégrées** - Suivez les économies de tokens localement
+- **Repli silencieux** - Ne perturbe jamais votre flux de travail
+
+## Installation
+
+### Option A : Plugin Claude Code (Recommandé) ⭐
+
+**Optimisation automatique des tokens sans appels manuels :**
+
+```bash
+# 1. Installer globalement
+npm install -g toonify-mcp
+
+# 2. Ajouter comme plugin (mode automatique)
+claude plugin add toonify-mcp
+
+# 3. Vérifier l'installation
+claude plugin list
+# Devrait afficher : toonify-mcp ✓
+```
+
+**C'est tout !** Le hook PostToolUse interceptera et optimisera automatiquement les données structurées provenant de Read, Grep et d'autres outils de fichiers.
+
+### Option B : Serveur MCP (Mode manuel)
+
+**Pour un contrôle explicite ou d'autres clients MCP :**
+
+```bash
+# 1. Installer globalement
+npm install -g toonify-mcp
+
+# 2. Enregistrer comme serveur MCP
+claude mcp add toonify -- toonify-mcp
+
+# 3. Vérifier
+claude mcp list
+# Devrait afficher : toonify: toonify-mcp - ✓ Connected
+```
+
+Ensuite, appelez les outils explicitement :
+```bash
+claude mcp call toonify optimize_content '{"content": "..."}'
+claude mcp call toonify get_stats '{}'
+```
+
+## Comment ça marche
+
+### Mode Plugin (Automatique)
+
+```
+Utilisateur : Lire un gros fichier JSON
+  ↓
+Claude Code appelle l'outil Read
+  ↓
+Le hook PostToolUse intercepte le résultat
+  ↓
+Le hook détecte le JSON, convertit en TOON
+  ↓
+Contenu optimisé envoyé à l'API Claude
+  ↓
+Réduction typique de 50 à 55 % des tokens obtenue ✨
+```
+
+### Mode Serveur MCP (Manuel)
+
+```
+Utilisateur : appelle explicitement mcp__toonify__optimize_content
+  ↓
+Contenu converti au format TOON
+  ↓
+Retourne le résultat optimisé
+```
+
+## Configuration
+
+Créez `~/.claude/toonify-config.json` (optionnel) :
+
+```json
+{
+  "enabled": true,
+  "minTokensThreshold": 50,
+  "minSavingsThreshold": 30,
+  "skipToolPatterns": ["Bash", "Write", "Edit"]
+}
+```
+
+### Options
+
+- **enabled** : Activer/désactiver l'optimisation automatique (par défaut : `true`)
+- **minTokensThreshold** : Nombre minimum de tokens avant optimisation (par défaut : `50`)
+- **minSavingsThreshold** : Pourcentage minimum d'économies requis (par défaut : `30%`)
+- **skipToolPatterns** : Outils à ne jamais optimiser (par défaut : `["Bash", "Write", "Edit"]`)
+
+### Variables d'environnement
+
+```bash
+export TOONIFY_ENABLED=true
+export TOONIFY_MIN_TOKENS=50
+export TOONIFY_MIN_SAVINGS=30
+export TOONIFY_SKIP_TOOLS="Bash,Write"
+export TOONIFY_SHOW_STATS=true  # Afficher les statistiques d'optimisation dans la sortie
+```
+
+## Exemples
+
+### Avant optimisation (142 tokens)
+
+```json
+{
+  "products": [
+    {"id": 101, "name": "Laptop Pro", "price": 1299},
+    {"id": 102, "name": "Magic Mouse", "price": 79}
+  ]
+}
+```
+
+### Après optimisation (57 tokens, -60 %)
+
+```
+[TOON-JSON]
+products[2]{id,name,price}:
+  101,Laptop Pro,1299
+  102,Magic Mouse,79
+```
+
+**Appliqué automatiquement en mode Plugin - aucun appel manuel nécessaire !**
+
+## Conseils d'utilisation
+
+### Quand l'optimisation automatique se déclenche-t-elle ?
+
+Le hook PostToolUse optimise automatiquement lorsque :
+- ✅ Le contenu est un JSON, CSV ou YAML valide
+- ✅ La taille du contenu ≥ `minTokensThreshold` (par défaut : 50 tokens)
+- ✅ Les économies estimées ≥ `minSavingsThreshold` (par défaut : 30 %)
+- ✅ L'outil n'est PAS dans `skipToolPatterns` (par ex., pas Bash/Write/Edit)
+
+### Voir les statistiques d'optimisation
+
+```bash
+# En mode Plugin
+claude mcp call toonify get_stats '{}'
+
+# Ou vérifier la sortie de Claude Code pour les statistiques (si TOONIFY_SHOW_STATS=true)
+```
+
+## Dépannage
+
+### Le hook ne se déclenche pas
+
+```bash
+# 1. Vérifier que le plugin est installé
+claude plugin list | grep toonify
+
+# 2. Vérifier la configuration
+cat ~/.claude/toonify-config.json
+
+# 3. Activer les statistiques pour voir les tentatives d'optimisation
+export TOONIFY_SHOW_STATS=true
+```
+
+### L'optimisation n'est pas appliquée
+
+- Vérifiez `minTokensThreshold` - le contenu pourrait être trop petit
+- Vérifiez `minSavingsThreshold` - les économies pourraient être < 30 %
+- Vérifiez `skipToolPatterns` - l'outil pourrait être dans la liste d'exclusion
+- Vérifiez que le contenu est un JSON/CSV/YAML valide
+
+### Problèmes de performance
+
+- Réduisez `minTokensThreshold` pour optimiser de manière plus agressive
+- Augmentez `minSavingsThreshold` pour ignorer les optimisations marginales
+- Ajoutez plus d'outils à `skipToolPatterns` si nécessaire
+
+## Comparaison : Plugin vs Serveur MCP
+
+| Fonctionnalité | Mode Plugin | Mode Serveur MCP |
+|----------------|-------------|------------------|
+| **Activation** | Automatique (PostToolUse) | Manuelle (appel d'outil) |
+| **Compatibilité** | Claude Code uniquement | Tout client MCP |
+| **Configuration** | Fichier de configuration du plugin | Outils MCP |
+| **Performance** | Aucun surcoût | Surcoût d'appel |
+| **Cas d'usage** | Flux de travail quotidien | Contrôle explicite |
+
+**Recommandation** : Utilisez le mode Plugin pour l'optimisation automatique. Utilisez le mode Serveur MCP pour un contrôle explicite ou d'autres clients MCP.
+
+## Désinstallation
+
+### Mode Plugin
+```bash
+claude plugin remove toonify-mcp
+rm ~/.claude/toonify-config.json
+```
+
+### Mode Serveur MCP
+```bash
+claude mcp remove toonify
+```
+
+### Package
+```bash
+npm uninstall -g toonify-mcp
+```
+
+## Liens
+
+- **GitHub** : https://github.com/kevintseng/toonify-mcp
+- **Issues** : https://github.com/kevintseng/toonify-mcp/issues
+- **NPM** : https://www.npmjs.com/package/toonify-mcp
+- **Documentation MCP** : https://code.claude.com/docs/mcp
+- **Format TOON** : https://github.com/toon-format/toon
+
+## Contribution
+
+Les contributions sont les bienvenues ! Veuillez consulter [CONTRIBUTING.md](CONTRIBUTING.md) pour les directives.
+
+## Licence
+
+Licence MIT - voir [LICENSE](LICENSE)
+
+## Journal des modifications
+
+### v0.3.0 (2025-12-26)
+- ✨ **Optimisation multilingue des tokens** - comptage précis pour plus de 15 langues
+- ✨ Multiplicateurs de tokens adaptés aux langues (2x chinois, 2,5x japonais, 3x arabe, etc.)
+- ✨ Détection et optimisation des textes multilingues
+- ✨ Tests de référence complets avec statistiques réelles
+- 📊 Revendications d'économies de tokens basées sur des données (plage de 30 à 65 %, typiquement 50 à 55 %)
+- ✅ Plus de 75 tests réussis, y compris les cas limites multilingues
+- 📝 Versions multilingues du README
+
+### v0.2.0 (2025-12-25)
+- ✨ Ajout du support du Plugin Claude Code avec hook PostToolUse
+- ✨ Optimisation automatique des tokens (aucun appel manuel nécessaire)
+- ✨ Système de configuration du plugin
+- ✨ Mode double : Plugin (auto) + Serveur MCP (manuel)
+- 📝 Mise à jour complète de la documentation
+
+### v0.1.1 (2024-12-24)
+- 🐛 Corrections de bugs et améliorations
+- 📝 Mises à jour de la documentation
+
+### v0.1.0 (2024-12-24)
+- 🎉 Version initiale
+- ✨ Implémentation du serveur MCP
+- ✨ Optimisation au format TOON
+- ✨ Suivi des métriques intégré

package/README.id.md

@@ -0,0 +1,270 @@
+# 🎯 Toonify MCP
+
+**[English](README.md) | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md) | [日本語](README.ja.md) | [Español](README.es.md) | [Français](README.fr.md) | [Deutsch](README.de.md) | [한국어](README.ko.md) | [Русский](README.ru.md) | [Português](README.pt.md) | [Tiếng Việt](README.vi.md) | [Bahasa Indonesia](README.id.md)**
+
+Server MCP + Plugin Claude Code yang menyediakan optimasi token otomatis untuk data terstruktur.
+Mengurangi penggunaan token Claude API sebesar **30-65% tergantung struktur data** melalui konversi format TOON yang transparan, dengan penghematan tipikal **50-55%** untuk data terstruktur.
+
+## Fitur Baru di v0.3.0
+
+✨ **Optimasi Token Multibahasa!**
+- ✅ Penghitungan token yang akurat untuk 15+ bahasa (Mandarin, Jepang, Korea, Spanyol, Arab, dll.)
+- ✅ Pengali token sadar bahasa (2x untuk Mandarin, 2.5x untuk Jepang, 3x untuk Arab)
+- ✅ Dukungan deteksi otomatis teks campuran multibahasa
+- ✅ Peningkatan akurasi optimasi berdasarkan tes benchmark nyata
+- ✅ Klaim penghematan token yang didukung data (rentang 30-65%, biasanya 50-55%)
+
+## Fitur
+
+- **Pengurangan Token 30-65%** (biasanya 50-55%) untuk data JSON, CSV, YAML
+- **Dukungan Multibahasa** - Penghitungan token akurat untuk 15+ bahasa
+- **Sepenuhnya Otomatis** - Hook PostToolUse mencegat hasil tool
+- **Tanpa Konfigurasi** - Bekerja langsung dengan nilai default yang masuk akal
+- **Mode Ganda** - Bekerja sebagai plugin (otomatis) atau server MCP (manual)
+- **Metrik Bawaan** - Melacak penghematan token secara lokal
+- **Fallback Senyap** - Tidak pernah mengganggu alur kerja Anda
+
+## Instalasi
+
+### Opsi A: Plugin Claude Code (Direkomendasikan) ⭐
+
+**Optimasi token otomatis tanpa panggilan manual:**
+
+```bash
+# 1. Instal global
+npm install -g toonify-mcp
+
+# 2. Tambahkan sebagai plugin (mode otomatis)
+claude plugin add toonify-mcp
+
+# 3. Verifikasi instalasi
+claude plugin list
+# Seharusnya menampilkan: toonify-mcp ✓
+```
+
+**Selesai!** Hook PostToolUse sekarang akan secara otomatis mencegat dan mengoptimalkan data terstruktur dari Read, Grep, dan tool file lainnya.
+
+### Opsi B: Server MCP (mode manual)
+
+**Untuk kontrol eksplisit atau klien MCP non-Claude Code:**
+
+```bash
+# 1. Instal global
+npm install -g toonify-mcp
+
+# 2. Daftarkan sebagai server MCP
+claude mcp add toonify -- toonify-mcp
+
+# 3. Verifikasi
+claude mcp list
+# Seharusnya menampilkan: toonify: toonify-mcp - ✓ Connected
+```
+
+Kemudian panggil tool secara eksplisit:
+```bash
+claude mcp call toonify optimize_content '{"content": "..."}'
+claude mcp call toonify get_stats '{}'
+```
+
+## Cara Kerja
+
+### Mode Plugin (otomatis)
+
+```
+Pengguna: Baca file JSON besar
+  ↓
+Claude Code memanggil tool Read
+  ↓
+Hook PostToolUse mencegat hasil
+  ↓
+Hook mendeteksi JSON, konversi ke TOON
+  ↓
+Konten yang dioptimalkan dikirim ke Claude API
+  ↓
+Pengurangan token tipikal 50-55% tercapai ✨
+```
+
+### Mode Server MCP (manual)
+
+```
+Pengguna: Panggil mcp__toonify__optimize_content secara eksplisit
+  ↓
+Konten dikonversi ke format TOON
+  ↓
+Mengembalikan hasil yang dioptimalkan
+```
+
+## Konfigurasi
+
+Buat `~/.claude/toonify-config.json` (opsional):
+
+```json
+{
+  "enabled": true,
+  "minTokensThreshold": 50,
+  "minSavingsThreshold": 30,
+  "skipToolPatterns": ["Bash", "Write", "Edit"]
+}
+```
+
+### Opsi
+
+- **enabled**: Aktifkan/nonaktifkan optimasi otomatis (default: `true`)
+- **minTokensThreshold**: Token minimum sebelum optimasi (default: `50`)
+- **minSavingsThreshold**: Persentase penghematan minimum yang diperlukan (default: `30%`)
+- **skipToolPatterns**: Tool yang tidak pernah dioptimalkan (default: `["Bash", "Write", "Edit"]`)
+
+### Variabel Lingkungan
+
+```bash
+export TOONIFY_ENABLED=true
+export TOONIFY_MIN_TOKENS=50
+export TOONIFY_MIN_SAVINGS=30
+export TOONIFY_SKIP_TOOLS="Bash,Write"
+export TOONIFY_SHOW_STATS=true  # Tampilkan statistik optimasi dalam output
+```
+
+## Contoh
+
+### Sebelum Optimasi (142 token)
+
+```json
+{
+  "products": [
+    {"id": 101, "name": "Laptop Pro", "price": 1299},
+    {"id": 102, "name": "Magic Mouse", "price": 79}
+  ]
+}
+```
+
+### Setelah Optimasi (57 token, -60%)
+
+```
+[TOON-JSON]
+products[2]{id,name,price}:
+  101,Laptop Pro,1299
+  102,Magic Mouse,79
+```
+
+**Diterapkan secara otomatis dalam mode plugin - tidak perlu panggilan manual!**
+
+## Tips Penggunaan
+
+### Kapan Optimasi Otomatis Dipicu?
+
+Hook PostToolUse secara otomatis mengoptimalkan ketika:
+- ✅ Konten adalah JSON, CSV, atau YAML yang valid
+- ✅ Ukuran konten ≥ `minTokensThreshold` (default: 50 token)
+- ✅ Perkiraan penghematan ≥ `minSavingsThreshold` (default: 30%)
+- ✅ Tool TIDAK ada dalam `skipToolPatterns` (misalnya, bukan Bash/Write/Edit)
+
+### Lihat Statistik Optimasi
+
+```bash
+# Dalam mode plugin
+claude mcp call toonify get_stats '{}'
+
+# Atau periksa output Claude Code untuk statistik (jika TOONIFY_SHOW_STATS=true)
+```
+
+## Pemecahan Masalah
+
+### Hook Tidak Terpicu
+
+```bash
+# 1. Periksa plugin sudah diinstal
+claude plugin list | grep toonify
+
+# 2. Periksa konfigurasi
+cat ~/.claude/toonify-config.json
+
+# 3. Aktifkan statistik untuk melihat percobaan optimasi
+export TOONIFY_SHOW_STATS=true
+```
+
+### Optimasi Tidak Diterapkan
+
+- Periksa `minTokensThreshold` - konten mungkin terlalu kecil
+- Periksa `minSavingsThreshold` - penghematan mungkin < 30%
+- Periksa `skipToolPatterns` - tool mungkin ada dalam daftar lewati
+- Verifikasi konten adalah JSON/CSV/YAML yang valid
+
+### Masalah Kinerja
+
+- Kurangi `minTokensThreshold` untuk mengoptimalkan lebih agresif
+- Tingkatkan `minSavingsThreshold` untuk melewati optimasi marginal
+- Tambahkan lebih banyak tool ke `skipToolPatterns` jika diperlukan
+
+## Perbandingan: Plugin vs Server MCP
+
+| Fitur | Mode Plugin | Mode Server MCP |
+|-------|------------|----------------|
+| **Aktivasi** | Otomatis (PostToolUse) | Manual (panggil tool) |
+| **Kompatibilitas** | Hanya Claude Code | Klien MCP apa pun |
+| **Konfigurasi** | File konfigurasi plugin | Tool MCP |
+| **Kinerja** | Tanpa overhead | Overhead panggilan |
+| **Use Case** | Alur kerja sehari-hari | Kontrol eksplisit |
+
+**Rekomendasi**: Gunakan mode plugin untuk optimasi otomatis. Gunakan mode server MCP untuk kontrol eksplisit atau klien MCP lainnya.
+
+## Uninstall
+
+### Mode Plugin
+```bash
+claude plugin remove toonify-mcp
+rm ~/.claude/toonify-config.json
+```
+
+### Mode Server MCP
+```bash
+claude mcp remove toonify
+```
+
+### Paket
+```bash
+npm uninstall -g toonify-mcp
+```
+
+## Tautan
+
+- **GitHub**: https://github.com/kevintseng/toonify-mcp
+- **Issues**: https://github.com/kevintseng/toonify-mcp/issues
+- **NPM**: https://www.npmjs.com/package/toonify-mcp
+- **Dokumentasi MCP**: https://code.claude.com/docs/mcp
+- **Format TOON**: https://github.com/toon-format/toon
+
+## Kontribusi
+
+Kontribusi sangat disambut! Silakan lihat [CONTRIBUTING.md](CONTRIBUTING.md) untuk panduan.
+
+## Lisensi
+
+Lisensi MIT - lihat [LICENSE](LICENSE)
+
+## Catatan Perubahan
+
+### v0.3.0 (2025-12-26)
+- ✨ **Optimasi token multibahasa** - penghitungan akurat untuk 15+ bahasa
+- ✨ Pengali token sadar bahasa (2x Mandarin, 2.5x Jepang, 3x Arab, dll.)
+- ✨ Deteksi dan optimasi teks campuran multibahasa
+- ✨ Tes benchmark komprehensif dengan statistik nyata
+- 📊 Klaim penghematan token yang didukung data (rentang 30-65%, biasanya 50-55%)
+- ✅ 75+ tes lulus, termasuk kasus edge multibahasa
+- 📝 Versi README multibahasa
+
+### v0.2.0 (2025-12-25)
+- ✨ Menambahkan dukungan plugin Claude Code dengan hook PostToolUse
+- ✨ Optimasi token otomatis (tidak perlu panggilan manual)
+- ✨ Sistem konfigurasi plugin
+- ✨ Mode ganda: Plugin (otomatis) + Server MCP (manual)
+- 📝 Pembaruan dokumentasi komprehensif
+
+### v0.1.1 (2024-12-24)
+- 🐛 Perbaikan bug dan peningkatan
+- 📝 Pembaruan dokumentasi
+
+### v0.1.0 (2024-12-24)
+- 🎉 Rilis awal
+- ✨ Implementasi server MCP
+- ✨ Optimasi format TOON
+- ✨ Pelacakan metrik bawaan