toonify-mcp 0.3.0 → 0.3.1

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
+- ✨ Встроенное отслеживание метрик

package/README.vi.md

@@ -1,6 +1,6 @@
 # 🎯 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)**
+**[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)**
 
 Máy chủ MCP + Plugin Claude Code cung cấp tối ưu hóa token tự động cho dữ liệu có cấu trúc.
 Giảm 30-65% việc sử dụng token của Claude API **tùy thuộc vào cấu trúc dữ liệu** thông qua chuyển đổi định dạng TOON minh bạch, với mức tiết kiệm điển hình **50-55%** cho dữ liệu có cấu trúc.

package/README.zh-CN.md

@@ -1,6 +1,6 @@
 # 🎯 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)**
+**[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 插件，提供结构化数据的自动 token 优化。
 通过透明的 TOON 格式转换，**根据数据结构减少 30-65% 的 Claude API token 使用量**，结构化数据的典型节省率为 **50-55%**。

package/README.zh-TW.md

@@ -1,6 +1,6 @@
 # 🎯 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)**
+**[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 外掛程式，提供結構化數據的自動 token 優化。
 透過透明的 TOON 格式轉換，**根據數據結構減少 30-65% 的 Claude API token 使用量**，結構化數據的典型節省率為 **50-55%**。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toonify-mcp",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "MCP server + Claude Code Plugin for TOON format token optimization. Reduces token usage by 30-65% (typically 50-55%) on JSON/CSV/YAML data via multilingual-aware optimization.",
   "type": "module",
   "main": "dist/index.js",