toonify-mcp 0.2.3 → 0.3.1

package/README.pt.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 Claude Code fornecendo otimização automática de tokens para dados estruturados.
+Reduz o uso de tokens da API do Claude em **30-65% dependendo da estrutura de dados** através da conversão transparente para o formato TOON, com economias típicas de **50-55%** para dados estruturados.
+
+## Novidades na v0.3.0
+
+✨ **Otimização Multilíngue de Tokens!**
+- ✅ Contagem precisa de tokens para mais de 15 idiomas (chinês, japonês, coreano, espanhol, árabe, etc.)
+- ✅ Multiplicadores de tokens conscientes do idioma (2x para chinês, 2.5x para japonês, 3x para árabe)
+- ✅ Suporte a textos em idiomas mistos com detecção automática
+- ✅ Precisão de otimização aprimorada baseada em benchmarks reais
+- ✅ Economia de tokens comprovada por dados (faixa de 30-65%, tipicamente 50-55%)
+
+## Recursos
+
+- **Redução de 30-65% de Tokens** (tipicamente 50-55%) para dados JSON, CSV, YAML
+- **Suporte Multilíngue** - Contagem precisa de tokens para mais de 15 idiomas
+- **Totalmente Automático** - Hook PostToolUse intercepta resultados de ferramentas
+- **Configuração Zero** - Funciona imediatamente com padrões sensatos
+- **Modo Duplo** - Funciona como Plugin (automático) ou Servidor MCP (manual)
+- **Métricas Integradas** - Rastreie economia de tokens localmente
+- **Fallback Silencioso** - Nunca quebra seu fluxo de trabalho
+
+## Instalação
+
+### Opção A: Plugin Claude Code (Recomendado) ⭐
+
+**Otimização automática de tokens sem chamadas manuais:**
+
+```bash
+# 1. Instalar globalmente
+npm install -g toonify-mcp
+
+# 2. Adicionar como plugin (modo automático)
+claude plugin add toonify-mcp
+
+# 3. Verificar instalação
+claude plugin list
+# Deve mostrar: toonify-mcp ✓
+```
+
+**É isso!** O hook PostToolUse agora interceptará e otimizará automaticamente dados estruturados do Read, Grep e outras ferramentas de arquivo.
+
+### Opção B: Servidor MCP (Modo manual)
+
+**Para controle explícito ou clientes MCP não-Claude Code:**
+
+```bash
+# 1. Instalar globalmente
+npm install -g toonify-mcp
+
+# 2. Registrar como servidor MCP
+claude mcp add toonify -- toonify-mcp
+
+# 3. Verificar
+claude mcp list
+# Deve mostrar: toonify: toonify-mcp - ✓ Connected
+```
+
+Então chame as ferramentas explicitamente:
+```bash
+claude mcp call toonify optimize_content '{"content": "..."}'
+claude mcp call toonify get_stats '{}'
+```
+
+## Como Funciona
+
+### Modo Plugin (Automático)
+
+```
+Usuário: Ler arquivo JSON grande
+  ↓
+Claude Code chama ferramenta Read
+  ↓
+Hook PostToolUse intercepta resultado
+  ↓
+Hook detecta JSON, converte para TOON
+  ↓
+Conteúdo otimizado enviado à API Claude
+  ↓
+Redução típica de 50-55% de tokens alcançada ✨
+```
+
+### Modo Servidor MCP (Manual)
+
+```
+Usuário: chama explicitamente mcp__toonify__optimize_content
+  ↓
+Conteúdo convertido para formato TOON
+  ↓
+Retorna resultado otimizado
+```
+
+## Configuração
+
+Crie `~/.claude/toonify-config.json` (opcional):
+
+```json
+{
+  "enabled": true,
+  "minTokensThreshold": 50,
+  "minSavingsThreshold": 30,
+  "skipToolPatterns": ["Bash", "Write", "Edit"]
+}
+```
+
+### Opções
+
+- **enabled**: Habilitar/desabilitar otimização automática (padrão: `true`)
+- **minTokensThreshold**: Tokens mínimos antes da otimização (padrão: `50`)
+- **minSavingsThreshold**: Porcentagem mínima de economia necessária (padrão: `30%`)
+- **skipToolPatterns**: Ferramentas que nunca serão otimizadas (padrão: `["Bash", "Write", "Edit"]`)
+
+### Variáveis de Ambiente
+
+```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 estatísticas de otimização na saída
+```
+
+## Exemplos
+
+### Antes da Otimização (142 tokens)
+
+```json
+{
+  "products": [
+    {"id": 101, "name": "Laptop Pro", "price": 1299},
+    {"id": 102, "name": "Magic Mouse", "price": 79}
+  ]
+}
+```
+
+### Depois da Otimização (57 tokens, -60%)
+
+```
+[TOON-JSON]
+products[2]{id,name,price}:
+  101,Laptop Pro,1299
+  102,Magic Mouse,79
+```
+
+**Aplicado automaticamente no modo Plugin - não são necessárias chamadas manuais!**
+
+## Dicas de Uso
+
+### Quando a Otimização Automática é Acionada?
+
+O hook PostToolUse otimiza automaticamente quando:
+- ✅ Conteúdo é JSON, CSV ou YAML válido
+- ✅ Tamanho do conteúdo ≥ `minTokensThreshold` (padrão: 50 tokens)
+- ✅ Economia estimada ≥ `minSavingsThreshold` (padrão: 30%)
+- ✅ Ferramenta NÃO está em `skipToolPatterns` (ex: não Bash/Write/Edit)
+
+### Visualizar Estatísticas de Otimização
+
+```bash
+# No modo Plugin
+claude mcp call toonify get_stats '{}'
+
+# Ou verifique a saída do Claude Code para estatísticas (se TOONIFY_SHOW_STATS=true)
+```
+
+## Solução de Problemas
+
+### Hook Não Está Sendo Acionado
+
+```bash
+# 1. Verificar se o plugin está instalado
+claude plugin list | grep toonify
+
+# 2. Verificar configuração
+cat ~/.claude/toonify-config.json
+
+# 3. Habilitar estatísticas para ver tentativas de otimização
+export TOONIFY_SHOW_STATS=true
+```
+
+### Otimização Não Aplicada
+
+- Verifique `minTokensThreshold` - conteúdo pode ser muito pequeno
+- Verifique `minSavingsThreshold` - economia pode ser < 30%
+- Verifique `skipToolPatterns` - ferramenta pode estar na lista de exclusão
+- Verifique se o conteúdo é JSON/CSV/YAML válido
+
+### Problemas de Desempenho
+
+- Reduza `minTokensThreshold` para otimizar mais agressivamente
+- Aumente `minSavingsThreshold` para pular otimizações marginais
+- Adicione mais ferramentas a `skipToolPatterns` se necessário
+
+## Comparação: Plugin vs Servidor MCP
+
+| Recurso | Modo Plugin | Modo Servidor MCP |
+|---------|------------|-----------------|
+| **Ativação** | Automática (PostToolUse) | Manual (chamar ferramenta) |
+| **Compatibilidade** | Apenas Claude Code | Qualquer cliente MCP |
+| **Configuração** | Arquivo de config do plugin | Ferramentas MCP |
+| **Desempenho** | Overhead zero | Overhead de chamada |
+| **Caso de Uso** | Fluxo de trabalho diário | Controle explícito |
+
+**Recomendação**: Use o modo Plugin para otimização automática. Use o modo Servidor MCP para controle explícito ou outros clientes MCP.
+
+## Desinstalar
+
+### Modo Plugin
+```bash
+claude plugin remove toonify-mcp
+rm ~/.claude/toonify-config.json
+```
+
+### Modo Servidor MCP
+```bash
+claude mcp remove toonify
+```
+
+### Pacote
+```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
+
+## Contribuindo
+
+Contribuições são bem-vindas! Por favor, consulte [CONTRIBUTING.md](CONTRIBUTING.md) para diretrizes.
+
+## Licença
+
+Licença MIT - veja [LICENSE](LICENSE)
+
+## Changelog
+
+### v0.3.0 (2025-12-26)
+- ✨ **Otimização multilíngue de tokens** - contagem precisa para mais de 15 idiomas
+- ✨ Multiplicadores de tokens conscientes do idioma (2x chinês, 2.5x japonês, 3x árabe, etc.)
+- ✨ Detecção e otimização de texto em idiomas mistos
+- ✨ Testes de benchmark abrangentes com estatísticas reais
+- 📊 Alegações de economia de tokens baseadas em dados (faixa de 30-65%, tipicamente 50-55%)
+- ✅ Mais de 75 testes passando, incluindo casos extremos multilíngues
+- 📝 Versões multilíngues do README
+
+### v0.2.0 (2025-12-25)
+- ✨ Adicionado suporte a Plugin Claude Code com hook PostToolUse
+- ✨ Otimização automática de tokens (não são necessárias chamadas manuais)
+- ✨ Sistema de configuração de plugin
+- ✨ Modo duplo: Plugin (automático) + Servidor MCP (manual)
+- 📝 Atualização abrangente da documentação
+
+### v0.1.1 (2024-12-24)
+- 🐛 Correções de bugs e melhorias
+- 📝 Atualizações de documentação
+
+### v0.1.0 (2024-12-24)
+- 🎉 Lançamento inicial
+- ✨ Implementação do Servidor MCP
+- ✨ Otimização de formato TOON
+- ✨ Rastreamento de métricas integrado

package/README.ru.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-сервер + плагин Claude Code, обеспечивающий автоматическую оптимизацию токенов для структурированных данных.
+Сокращает использование токенов Claude API на **30-65% в зависимости от структуры данных** благодаря прозрачному преобразованию в формат TOON, с типичной экономией **50-55%** для структурированных данных.
+
+## Что нового в v0.3.0
+
+✨ **Многоязычная оптимизация токенов!**
+- ✅ Точный подсчет токенов для 15+ языков (китайский, японский, корейский, испанский, арабский и др.)
+- ✅ Языково-зависимые множители токенов (2x для китайского, 2.5x для японского, 3x для арабского)
+- ✅ Поддержка смешанных языков с автоматическим определением
+- ✅ Улучшенная точность оптимизации на основе реальных тестов
+- ✅ Подтвержденные данными заявления об экономии токенов (диапазон 30-65%, обычно 50-55%)
+
+## Возможности
+
+- **Сокращение токенов на 30-65%** (обычно 50-55%) для данных JSON, CSV, YAML
+- **Многоязычная поддержка** - точный подсчет токенов для 15+ языков
+- **Полностью автоматический режим** - хук PostToolUse перехватывает результаты инструментов
+- **Нулевая конфигурация** - работает из коробки с разумными настройками по умолчанию
+- **Двойной режим** - работает как плагин (авто) или MCP-сервер (вручную)
+- **Встроенные метрики** - отслеживание экономии токенов локально
+- **Тихий откат** - никогда не нарушает ваш рабочий процесс
+
+## Установка
+
+### Вариант A: Плагин Claude Code (Рекомендуется) ⭐
+
+**Автоматическая оптимизация токенов без ручных вызовов:**
+
+```bash
+# 1. Установить глобально
+npm install -g toonify-mcp
+
+# 2. Добавить как плагин (автоматический режим)
+claude plugin add toonify-mcp
+
+# 3. Проверить установку
+claude plugin list
+# Должно показать: toonify-mcp ✓
+```
+
+**Вот и всё!** Хук PostToolUse теперь будет автоматически перехватывать и оптимизировать структурированные данные из инструментов Read, Grep и других файловых инструментов.
+
+### Вариант B: MCP-сервер (Ручной режим)
+
+**Для явного контроля или других MCP-клиентов:**
+
+```bash
+# 1. Установить глобально
+npm install -g toonify-mcp
+
+# 2. Зарегистрировать как MCP-сервер
+claude mcp add toonify -- toonify-mcp
+
+# 3. Проверить
+claude mcp list
+# Должно показать: toonify: toonify-mcp - ✓ Connected
+```
+
+Затем вызывайте инструменты явно:
+```bash
+claude mcp call toonify optimize_content '{"content": "..."}'
+claude mcp call toonify get_stats '{}'
+```
+
+## Как это работает
+
+### Режим плагина (Автоматический)
+
+```
+Пользователь: Прочитать большой JSON-файл
+  ↓
+Claude Code вызывает инструмент Read
+  ↓
+Хук PostToolUse перехватывает результат
+  ↓
+Хук определяет JSON, преобразует в TOON
+  ↓
+Оптимизированный контент отправляется в Claude API
+  ↓
+Достигается типичное сокращение токенов на 50-55% ✨
+```
+
+### Режим MCP-сервера (Ручной)
+
+```
+Пользователь: явно вызывает mcp__toonify__optimize_content
+  ↓
+Контент преобразуется в формат TOON
+  ↓
+Возвращается оптимизированный результат
+```
+
+## Конфигурация
+
+Создайте `~/.claude/toonify-config.json` (необязательно):
+
+```json
+{
+  "enabled": true,
+  "minTokensThreshold": 50,
+  "minSavingsThreshold": 30,
+  "skipToolPatterns": ["Bash", "Write", "Edit"]
+}
+```
+
+### Параметры
+
+- **enabled**: Включить/отключить автоматическую оптимизацию (по умолчанию: `true`)
+- **minTokensThreshold**: Минимальное количество токенов перед оптимизацией (по умолчанию: `50`)
+- **minSavingsThreshold**: Минимальный требуемый процент экономии (по умолчанию: `30%`)
+- **skipToolPatterns**: Инструменты, которые никогда не оптимизировать (по умолчанию: `["Bash", "Write", "Edit"]`)
+
+### Переменные окружения
+
+```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  # Показывать статистику оптимизации в выводе
+```
+
+## Примеры
+
+### До оптимизации (142 токена)
+
+```json
+{
+  "products": [
+    {"id": 101, "name": "Laptop Pro", "price": 1299},
+    {"id": 102, "name": "Magic Mouse", "price": 79}
+  ]
+}
+```
+
+### После оптимизации (57 токенов, -60%)
+
+```
+[TOON-JSON]
+products[2]{id,name,price}:
+  101,Laptop Pro,1299
+  102,Magic Mouse,79
+```
+
+**Автоматически применяется в режиме плагина - ручные вызовы не нужны!**
+
+## Советы по использованию
+
+### Когда срабатывает автоматическая оптимизация?
+
+Хук PostToolUse автоматически оптимизирует, когда:
+- ✅ Контент является валидным JSON, CSV или YAML
+- ✅ Размер контента ≥ `minTokensThreshold` (по умолчанию: 50 токенов)
+- ✅ Предполагаемая экономия ≥ `minSavingsThreshold` (по умолчанию: 30%)
+- ✅ Инструмент НЕ входит в `skipToolPatterns` (например, не Bash/Write/Edit)
+
+### Просмотр статистики оптимизации
+
+```bash
+# В режиме плагина
+claude mcp call toonify get_stats '{}'
+
+# Или проверьте вывод Claude Code для статистики (если TOONIFY_SHOW_STATS=true)
+```
+
+## Устранение неполадок
+
+### Хук не срабатывает
+
+```bash
+# 1. Проверьте, что плагин установлен
+claude plugin list | grep toonify
+
+# 2. Проверьте конфигурацию
+cat ~/.claude/toonify-config.json
+
+# 3. Включите статистику для просмотра попыток оптимизации
+export TOONIFY_SHOW_STATS=true
+```
+
+### Оптимизация не применяется
+
+- Проверьте `minTokensThreshold` - контент может быть слишком мал
+- Проверьте `minSavingsThreshold` - экономия может быть < 30%
+- Проверьте `skipToolPatterns` - инструмент может быть в списке пропуска
+- Убедитесь, что контент является валидным JSON/CSV/YAML
+
+### Проблемы с производительностью
+
+- Уменьшите `minTokensThreshold` для более агрессивной оптимизации
+- Увеличьте `minSavingsThreshold` для пропуска незначительных оптимизаций
+- Добавьте больше инструментов в `skipToolPatterns` при необходимости
+
+## Сравнение: Плагин vs MCP-сервер
+
+| Функция | Режим плагина | Режим MCP-сервера |
+|---------|--------------|-------------------|
+| **Активация** | Автоматическая (PostToolUse) | Ручная (вызов инструмента) |
+| **Совместимость** | Только Claude Code | Любой MCP-клиент |
+| **Конфигурация** | Файл конфигурации плагина | Инструменты MCP |
+| **Производительность** | Нулевые накладные расходы | Накладные расходы на вызов |
+| **Сценарий использования** | Ежедневный рабочий процесс | Явный контроль |
+
+**Рекомендация**: Используйте режим плагина для автоматической оптимизации. Используйте режим MCP-сервера для явного контроля или других MCP-клиентов.
+
+## Удаление
+
+### Режим плагина
+```bash
+claude plugin remove toonify-mcp
+rm ~/.claude/toonify-config.json
+```
+
+### Режим MCP-сервера
+```bash
+claude mcp remove toonify
+```
+
+### Пакет
+```bash
+npm uninstall -g toonify-mcp
+```
+
+## Ссылки
+
+- **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
+
+## Вклад в проект
+
+Вклады приветствуются! Пожалуйста, ознакомьтесь с [CONTRIBUTING.md](CONTRIBUTING.md) для получения рекомендаций.
+
+## Лицензия
+
+Лицензия MIT - см. [LICENSE](LICENSE)
+
+## Changelog
+
+### v0.3.0 (2025-12-26)
+- ✨ **Многоязычная оптимизация токенов** - точный подсчет для 15+ языков
+- ✨ Языково-зависимые множители токенов (2x китайский, 2.5x японский, 3x арабский и др.)
+- ✨ Определение и оптимизация смешанных языков
+- ✨ Комплексное тестирование с реальной статистикой
+- 📊 Подтвержденные данными заявления об экономии токенов (диапазон 30-65%, обычно 50-55%)
+- ✅ 75+ пройденных тестов, включая многоязычные граничные случаи
+- 📝 Многоязычные версии README
+
+### v0.2.0 (2025-12-25)
+- ✨ Добавлена поддержка плагина Claude Code с хуком PostToolUse
+- ✨ Автоматическая оптимизация токенов (ручные вызовы не нужны)
+- ✨ Система конфигурации плагина
+- ✨ Двойной режим: Плагин (авто) + MCP-сервер (вручную)
+- 📝 Комплексное обновление документации
+
+### v0.1.1 (2024-12-24)
+- 🐛 Исправления ошибок и улучшения
+- 📝 Обновления документации
+
+### v0.1.0 (2024-12-24)
+- 🎉 Первый релиз
+- ✨ Реализация MCP-сервера
+- ✨ Оптимизация формата TOON
+- ✨ Встроенное отслеживание метрик