toonify-mcp 0.2.3 → 0.3.1

package/README.de.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)**
+
+MCP-Server + Claude Code Plugin zur automatischen Token-Optimierung für strukturierte Daten.
+Reduziert den Claude-API-Token-Verbrauch um **30-65% je nach Datenstruktur** durch transparente TOON-Format-Konvertierung, mit typischen Einsparungen von **50-55%** für strukturierte Daten.
+
+## Neu in v0.3.0
+
+✨ **Mehrsprachige Token-Optimierung!**
+- ✅ Präzise Token-Zählung für über 15 Sprachen (Chinesisch, Japanisch, Koreanisch, Spanisch, Arabisch, etc.)
+- ✅ Sprachabhängige Token-Multiplikatoren (2x für Chinesisch, 2,5x für Japanisch, 3x für Arabisch)
+- ✅ Unterstützung für mehrsprachige Texte mit automatischer Erkennung
+- ✅ Verbesserte Optimierungsgenauigkeit basierend auf echten Benchmarks
+- ✅ Datengestützte Token-Einsparungs-Angaben (30-65% Bereich, typischerweise 50-55%)
+
+## Funktionen
+
+- **30-65% Token-Reduktion** (typischerweise 50-55%) für JSON, CSV, YAML-Daten
+- **Mehrsprachige Unterstützung** - Präzise Token-Zählung für über 15 Sprachen
+- **Vollautomatisch** - PostToolUse-Hook fängt Tool-Ergebnisse ab
+- **Keine Konfiguration nötig** - Funktioniert sofort mit sinnvollen Standardwerten
+- **Dual-Modus** - Funktioniert als Plugin (automatisch) oder MCP-Server (manuell)
+- **Integrierte Metriken** - Verfolgt Token-Einsparungen lokal
+- **Stille Rückfall-Mechanismen** - Unterbricht niemals Ihren Workflow
+
+## Installation
+
+### Option A: Claude Code Plugin (Empfohlen) ⭐
+
+**Automatische Token-Optimierung ohne manuelle Aufrufe:**
+
+```bash
+# 1. Global installieren
+npm install -g toonify-mcp
+
+# 2. Als Plugin hinzufügen (automatischer Modus)
+claude plugin add toonify-mcp
+
+# 3. Installation überprüfen
+claude plugin list
+# Sollte anzeigen: toonify-mcp ✓
+```
+
+**Das war's!** Der PostToolUse-Hook wird nun automatisch strukturierte Daten von Read, Grep und anderen Datei-Tools abfangen und optimieren.
+
+### Option B: MCP-Server (Manueller Modus)
+
+**Für explizite Kontrolle oder andere MCP-Clients:**
+
+```bash
+# 1. Global installieren
+npm install -g toonify-mcp
+
+# 2. Als MCP-Server registrieren
+claude mcp add toonify -- toonify-mcp
+
+# 3. Überprüfen
+claude mcp list
+# Sollte anzeigen: toonify: toonify-mcp - ✓ Connected
+```
+
+Dann Tools explizit aufrufen:
+```bash
+claude mcp call toonify optimize_content '{"content": "..."}'
+claude mcp call toonify get_stats '{}'
+```
+
+## Funktionsweise
+
+### Plugin-Modus (Automatisch)
+
+```
+Benutzer: Liest große JSON-Datei
+  ↓
+Claude Code ruft Read-Tool auf
+  ↓
+PostToolUse-Hook fängt Ergebnis ab
+  ↓
+Hook erkennt JSON, konvertiert zu TOON
+  ↓
+Optimierter Inhalt wird an Claude-API gesendet
+  ↓
+50-55% typische Token-Reduktion erreicht ✨
+```
+
+### MCP-Server-Modus (Manuell)
+
+```
+Benutzer: ruft explizit mcp__toonify__optimize_content auf
+  ↓
+Inhalt wird in TOON-Format konvertiert
+  ↓
+Gibt optimiertes Ergebnis zurück
+```
+
+## Konfiguration
+
+Erstellen Sie `~/.claude/toonify-config.json` (optional):
+
+```json
+{
+  "enabled": true,
+  "minTokensThreshold": 50,
+  "minSavingsThreshold": 30,
+  "skipToolPatterns": ["Bash", "Write", "Edit"]
+}
+```
+
+### Optionen
+
+- **enabled**: Automatische Optimierung aktivieren/deaktivieren (Standard: `true`)
+- **minTokensThreshold**: Mindestanzahl an Token vor Optimierung (Standard: `50`)
+- **minSavingsThreshold**: Erforderlicher Mindest-Einsparungsprozentsatz (Standard: `30%`)
+- **skipToolPatterns**: Tools, die niemals optimiert werden (Standard: `["Bash", "Write", "Edit"]`)
+
+### Umgebungsvariablen
+
+```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  # Optimierungsstatistiken in Ausgabe anzeigen
+```
+
+## Beispiele
+
+### Vor der Optimierung (142 Token)
+
+```json
+{
+  "products": [
+    {"id": 101, "name": "Laptop Pro", "price": 1299},
+    {"id": 102, "name": "Magic Mouse", "price": 79}
+  ]
+}
+```
+
+### Nach der Optimierung (57 Token, -60%)
+
+```
+[TOON-JSON]
+products[2]{id,name,price}:
+  101,Laptop Pro,1299
+  102,Magic Mouse,79
+```
+
+**Wird automatisch im Plugin-Modus angewendet - keine manuellen Aufrufe erforderlich!**
+
+## Nutzungstipps
+
+### Wann wird die Auto-Optimierung ausgelöst?
+
+Der PostToolUse-Hook optimiert automatisch, wenn:
+- ✅ Inhalt valides JSON, CSV oder YAML ist
+- ✅ Inhaltsgröße ≥ `minTokensThreshold` (Standard: 50 Token)
+- ✅ Geschätzte Einsparungen ≥ `minSavingsThreshold` (Standard: 30%)
+- ✅ Tool NICHT in `skipToolPatterns` ist (z.B. nicht Bash/Write/Edit)
+
+### Optimierungsstatistiken anzeigen
+
+```bash
+# Im Plugin-Modus
+claude mcp call toonify get_stats '{}'
+
+# Oder überprüfen Sie die Claude Code-Ausgabe für Statistiken (wenn TOONIFY_SHOW_STATS=true)
+```
+
+## Fehlerbehebung
+
+### Hook wird nicht ausgelöst
+
+```bash
+# 1. Überprüfen, ob Plugin installiert ist
+claude plugin list | grep toonify
+
+# 2. Konfiguration überprüfen
+cat ~/.claude/toonify-config.json
+
+# 3. Statistiken aktivieren, um Optimierungsversuche zu sehen
+export TOONIFY_SHOW_STATS=true
+```
+
+### Optimierung wird nicht angewendet
+
+- Überprüfen Sie `minTokensThreshold` - Inhalt könnte zu klein sein
+- Überprüfen Sie `minSavingsThreshold` - Einsparungen könnten < 30% sein
+- Überprüfen Sie `skipToolPatterns` - Tool könnte in Ausschlussliste sein
+- Überprüfen Sie, ob Inhalt valides JSON/CSV/YAML ist
+
+### Leistungsprobleme
+
+- Reduzieren Sie `minTokensThreshold` für aggressivere Optimierung
+- Erhöhen Sie `minSavingsThreshold`, um marginale Optimierungen zu überspringen
+- Fügen Sie bei Bedarf mehr Tools zu `skipToolPatterns` hinzu
+
+## Vergleich: Plugin vs. MCP-Server
+
+| Funktion | Plugin-Modus | MCP-Server-Modus |
+|---------|------------|-----------------|
+| **Aktivierung** | Automatisch (PostToolUse) | Manuell (Tool aufrufen) |
+| **Kompatibilität** | Nur Claude Code | Jeder MCP-Client |
+| **Konfiguration** | Plugin-Konfigurationsdatei | MCP-Tools |
+| **Leistung** | Kein Overhead | Aufruf-Overhead |
+| **Anwendungsfall** | Täglicher Workflow | Explizite Kontrolle |
+
+**Empfehlung**: Verwenden Sie den Plugin-Modus für automatische Optimierung. Verwenden Sie den MCP-Server-Modus für explizite Kontrolle oder andere MCP-Clients.
+
+## Deinstallation
+
+### Plugin-Modus
+```bash
+claude plugin remove toonify-mcp
+rm ~/.claude/toonify-config.json
+```
+
+### MCP-Server-Modus
+```bash
+claude mcp remove toonify
+```
+
+### Paket
+```bash
+npm uninstall -g toonify-mcp
+```
+
+## Links
+
+- **GitHub**: https://github.com/kevintseng/toonify-mcp
+- **Issues**: https://github.com/kevintseng/toonify-mcp/issues
+- **NPM**: https://www.npmjs.com/package/toonify-mcp
+- **MCP Docs**: https://code.claude.com/docs/mcp
+- **TOON Format**: https://github.com/toon-format/toon
+
+## Mitwirken
+
+Beiträge sind willkommen! Bitte lesen Sie [CONTRIBUTING.md](CONTRIBUTING.md) für Richtlinien.
+
+## Lizenz
+
+MIT License - siehe [LICENSE](LICENSE)
+
+## Änderungsprotokoll
+
+### v0.3.0 (2025-12-26)
+- ✨ **Mehrsprachige Token-Optimierung** - präzise Zählung für über 15 Sprachen
+- ✨ Sprachabhängige Token-Multiplikatoren (2x Chinesisch, 2,5x Japanisch, 3x Arabisch, etc.)
+- ✨ Erkennung und Optimierung mehrsprachiger Texte
+- ✨ Umfassende Benchmark-Tests mit echten Statistiken
+- 📊 Datengestützte Token-Einsparungs-Angaben (30-65% Bereich, typischerweise 50-55%)
+- ✅ 75+ bestandene Tests, einschließlich mehrsprachiger Randfälle
+- 📝 Mehrsprachige README-Versionen
+
+### v0.2.0 (2025-12-25)
+- ✨ Claude Code Plugin-Unterstützung mit PostToolUse-Hook hinzugefügt
+- ✨ Automatische Token-Optimierung (keine manuellen Aufrufe erforderlich)
+- ✨ Plugin-Konfigurationssystem
+- ✨ Dual-Modus: Plugin (automatisch) + MCP-Server (manuell)
+- 📝 Umfassende Dokumentationsaktualisierung
+
+### v0.1.1 (2024-12-24)
+- 🐛 Fehlerbehebungen und Verbesserungen
+- 📝 Dokumentationsaktualisierungen
+
+### v0.1.0 (2024-12-24)
+- 🎉 Erstveröffentlichung
+- ✨ MCP-Server-Implementierung
+- ✨ TOON-Format-Optimierung
+- ✨ Integrierte Metrik-Verfolgung

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