toonify-mcp 0.2.3 → 0.3.0

package/README.es.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) | [Tiếng Việt](README.vi.md) | [Bahasa Indonesia](README.id.md)**
+
+Servidor MCP + Plugin de Claude Code que proporciona optimización automática de tokens para datos estructurados.
+Reduce el uso de tokens de la API de Claude en **30-65% según la estructura de datos** mediante conversión transparente al formato TOON, con ahorros típicos del **50-55%** para datos estructurados.
+
+## Novedades en v0.3.0
+
+✨ **¡Optimización de tokens multilingüe!**
+- ✅ Conteo preciso de tokens para más de 15 idiomas (chino, japonés, coreano, español, árabe, etc.)
+- ✅ Multiplicadores de tokens conscientes del idioma (2x para chino, 2.5x para japonés, 3x para árabe)
+- ✅ Soporte para detección automática de texto en idiomas mixtos
+- ✅ Precisión de optimización mejorada basada en pruebas de referencia reales
+- ✅ Afirmaciones de ahorro de tokens respaldadas por datos (rango 30-65%, típicamente 50-55%)
+
+## Características
+
+- **Reducción de tokens del 30-65%** (típicamente 50-55%) para datos JSON, CSV y YAML
+- **Soporte multilingüe** - Conteo preciso de tokens para más de 15 idiomas
+- **Completamente automático** - El hook PostToolUse intercepta resultados de herramientas
+- **Configuración cero** - Funciona inmediatamente con valores predeterminados sensatos
+- **Modo dual** - Funciona como plugin (automático) o servidor MCP (manual)
+- **Métricas integradas** - Rastrea el ahorro de tokens localmente
+- **Fallback silencioso** - Nunca interrumpe tu flujo de trabajo
+
+## Instalación
+
+### Opción A: Plugin de Claude Code (Recomendado) ⭐
+
+**Optimización automática de tokens sin llamadas manuales:**
+
+```bash
+# 1. Instalación global
+npm install -g toonify-mcp
+
+# 2. Agregar como plugin (modo automático)
+claude plugin add toonify-mcp
+
+# 3. Verificar instalación
+claude plugin list
+# Debería mostrar: toonify-mcp ✓
+```
+
+**¡Eso es todo!** El hook PostToolUse ahora interceptará y optimizará automáticamente los datos estructurados de Read, Grep y otras herramientas de archivos.
+
+### Opción B: Servidor MCP (modo manual)
+
+**Para control explícito o clientes MCP que no sean Claude Code:**
+
+```bash
+# 1. Instalación global
+npm install -g toonify-mcp
+
+# 2. Registrar como servidor MCP
+claude mcp add toonify -- toonify-mcp
+
+# 3. Verificar
+claude mcp list
+# Debería mostrar: toonify: toonify-mcp - ✓ Connected
+```
+
+Luego llamar a las herramientas explícitamente:
+```bash
+claude mcp call toonify optimize_content '{"content": "..."}'
+claude mcp call toonify get_stats '{}'
+```
+
+## Cómo funciona
+
+### Modo plugin (automático)
+
+```
+Usuario: Leer archivo JSON grande
+  ↓
+Claude Code llama a la herramienta Read
+  ↓
+El hook PostToolUse intercepta el resultado
+  ↓
+El hook detecta JSON, convierte a TOON
+  ↓
+Contenido optimizado enviado a la API de Claude
+  ↓
+Reducción típica de tokens del 50-55% lograda ✨
+```
+
+### Modo servidor MCP (manual)
+
+```
+Usuario: Llamar explícitamente a mcp__toonify__optimize_content
+  ↓
+El contenido se convierte a formato TOON
+  ↓
+Devuelve resultado optimizado
+```
+
+## Configuración
+
+Crear `~/.claude/toonify-config.json` (opcional):
+
+```json
+{
+  "enabled": true,
+  "minTokensThreshold": 50,
+  "minSavingsThreshold": 30,
+  "skipToolPatterns": ["Bash", "Write", "Edit"]
+}
+```
+
+### Opciones
+
+- **enabled**: Habilitar/deshabilitar optimización automática (predeterminado: `true`)
+- **minTokensThreshold**: Tokens mínimos antes de la optimización (predeterminado: `50`)
+- **minSavingsThreshold**: Porcentaje mínimo de ahorro requerido (predeterminado: `30%`)
+- **skipToolPatterns**: Herramientas que nunca optimizar (predeterminado: `["Bash", "Write", "Edit"]`)
+
+### Variables de entorno
+
+```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  # Mostrar estadísticas de optimización en la salida
+```
+
+## Ejemplos
+
+### Antes de la optimización (142 tokens)
+
+```json
+{
+  "products": [
+    {"id": 101, "name": "Laptop Pro", "price": 1299},
+    {"id": 102, "name": "Magic Mouse", "price": 79}
+  ]
+}
+```
+
+### Después de la optimización (57 tokens, -60%)
+
+```
+[TOON-JSON]
+products[2]{id,name,price}:
+  101,Laptop Pro,1299
+  102,Magic Mouse,79
+```
+
+**¡Se aplica automáticamente en modo plugin - no se necesitan llamadas manuales!**
+
+## Consejos de uso
+
+### ¿Cuándo se activa la optimización automática?
+
+El hook PostToolUse optimiza automáticamente cuando:
+- ✅ El contenido es JSON, CSV o YAML válido
+- ✅ Tamaño del contenido ≥ `minTokensThreshold` (predeterminado: 50 tokens)
+- ✅ Ahorro estimado ≥ `minSavingsThreshold` (predeterminado: 30%)
+- ✅ La herramienta NO está en `skipToolPatterns` (por ejemplo, no es Bash/Write/Edit)
+
+### Ver estadísticas de optimización
+
+```bash
+# En modo plugin
+claude mcp call toonify get_stats '{}'
+
+# O verificar la salida de Claude Code para estadísticas (si TOONIFY_SHOW_STATS=true)
+```
+
+## Solución de problemas
+
+### El hook no se activa
+
+```bash
+# 1. Verificar que el plugin esté instalado
+claude plugin list | grep toonify
+
+# 2. Verificar configuración
+cat ~/.claude/toonify-config.json
+
+# 3. Habilitar estadísticas para ver intentos de optimización
+export TOONIFY_SHOW_STATS=true
+```
+
+### La optimización no se aplica
+
+- Verificar `minTokensThreshold` - el contenido podría ser demasiado pequeño
+- Verificar `minSavingsThreshold` - el ahorro podría ser < 30%
+- Verificar `skipToolPatterns` - la herramienta podría estar en la lista de omisión
+- Verificar que el contenido sea JSON/CSV/YAML válido
+
+### Problemas de rendimiento
+
+- Reducir `minTokensThreshold` para optimizar más agresivamente
+- Aumentar `minSavingsThreshold` para omitir optimizaciones marginales
+- Agregar más herramientas a `skipToolPatterns` si es necesario
+
+## Comparación: Plugin vs Servidor MCP
+
+| Característica | Modo Plugin | Modo Servidor MCP |
+|----------------|------------|-------------------|
+| **Activación** | Automático (PostToolUse) | Manual (llamar herramienta) |
+| **Compatibilidad** | Solo Claude Code | Cualquier cliente MCP |
+| **Configuración** | Archivo de configuración de plugin | Herramientas MCP |
+| **Rendimiento** | Cero sobrecarga | Sobrecarga de llamada |
+| **Caso de uso** | Flujo de trabajo diario | Control explícito |
+
+**Recomendación**: Usar modo plugin para optimización automática. Usar modo servidor MCP para control explícito u otros clientes MCP.
+
+## Desinstalación
+
+### Modo plugin
+```bash
+claude plugin remove toonify-mcp
+rm ~/.claude/toonify-config.json
+```
+
+### Modo servidor MCP
+```bash
+claude mcp remove toonify
+```
+
+### Paquete
+```bash
+npm uninstall -g toonify-mcp
+```
+
+## Enlaces
+
+- **GitHub**: https://github.com/kevintseng/toonify-mcp
+- **Issues**: https://github.com/kevintseng/toonify-mcp/issues
+- **NPM**: https://www.npmjs.com/package/toonify-mcp
+- **Documentación MCP**: https://code.claude.com/docs/mcp
+- **Formato TOON**: https://github.com/toon-format/toon
+
+## Contribuir
+
+¡Las contribuciones son bienvenidas! Por favor, consulta [CONTRIBUTING.md](CONTRIBUTING.md) para obtener las pautas.
+
+## Licencia
+
+Licencia MIT - ver [LICENSE](LICENSE)
+
+## Registro de cambios
+
+### v0.3.0 (2025-12-26)
+- ✨ **Optimización de tokens multilingüe** - conteo preciso para más de 15 idiomas
+- ✨ Multiplicadores de tokens conscientes del idioma (2x chino, 2.5x japonés, 3x árabe, etc.)
+- ✨ Detección y optimización de texto en idiomas mixtos
+- ✨ Pruebas de referencia completas con estadísticas reales
+- 📊 Afirmaciones de ahorro de tokens respaldadas por datos (rango 30-65%, típicamente 50-55%)
+- ✅ Más de 75 pruebas pasadas, incluidos casos extremos multilingües
+- 📝 Versiones README multilingües
+
+### v0.2.0 (2025-12-25)
+- ✨ Soporte de plugin Claude Code agregado con hook PostToolUse
+- ✨ Optimización automática de tokens (no se necesitan llamadas manuales)
+- ✨ Sistema de configuración de plugin
+- ✨ Modo dual: Plugin (automático) + Servidor MCP (manual)
+- 📝 Actualización completa de la documentación
+
+### v0.1.1 (2024-12-24)
+- 🐛 Correcciones de errores y mejoras
+- 📝 Actualizaciones de documentación
+
+### v0.1.0 (2024-12-24)
+- 🎉 Lanzamiento inicial
+- ✨ Implementación del servidor MCP
+- ✨ Optimización de formato TOON
+- ✨ Seguimiento de métricas integrado

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