# 🎯 Toonify MCP

**[English](README.md) | [繁體中文](README.zh-TW.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.5.0

✨ **Обновления SDK и инструментов!**
- ✅ MCP SDK обновлен до линейки 1.25.x
- ✅ Обновлены зависимости tokenizer и YAML
- ✅ Миграция на Jest 30 с SWC-обработкой TypeScript ESM
- ✅ Исправления безопасности применены через npm audit

## Возможности

- **Сокращение токенов на 30-65%** (обычно 50-55%) для данных JSON, CSV, YAML
- **Многоязычная поддержка** - точный подсчет токенов для 15+ языков
- **Полностью автоматический режим** - хук PostToolUse перехватывает результаты инструментов
- **Нулевая конфигурация** - работает из коробки с разумными настройками по умолчанию
- **Двойной режим** - работает как плагин (авто) или MCP-сервер (вручную)
- **Встроенные метрики** - отслеживание экономии токенов локально
- **Тихий откат** - никогда не нарушает ваш рабочий процесс

## Установка

### Вариант A: Скачать с GitHub (Рекомендуется) 🌟

**Установка напрямую из GitHub-репозитория (публикация npm не требуется):**

```bash
# 1. Скачать репозиторий
git clone https://github.com/PCIRCLE-AI/toonify-mcp.git
cd toonify-mcp

# 2. Установить зависимости и собрать
npm install
npm run build

# 3. Установить глобально из локального источника
npm install -g .
```

### Вариант B: Установка из маркетплейса pcircle.ai (Проще всего) 🌟

**Установка в один клик:**

Перейдите в [маркетплейс pcircle.ai](https://claudemarketplaces.com) в Claude Code и установите toonify-mcp одним кликом. Маркетплейс обработает всё автоматически!

### Вариант C: Плагин Claude Code (Рекомендуется) ⭐

**Автоматическая оптимизация токенов без ручных вызовов:**

Предусловие: завершите вариант A или B, чтобы был доступен бинарник `toonify-mcp`.

```bash
# 1. Добавить как плагин (автоматический режим)
claude plugin add toonify-mcp

# 2. Проверить установку
claude plugin list
# Должно показать: toonify-mcp ✓
```

**Вот и всё!** Хук PostToolUse теперь будет автоматически перехватывать и оптимизировать структурированные данные из инструментов Read, Grep и других файловых инструментов.

### Вариант D: MCP-сервер (Ручной режим)

**Для явного контроля или других MCP-клиентов:**

Предусловие: завершите вариант A или B, чтобы был доступен бинарник `toonify-mcp`.

```bash
# 1. Зарегистрировать как MCP-сервер
claude mcp add toonify -- toonify-mcp

# 2. Проверить
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/PCIRCLE-AI/toonify-mcp
- **Issues**: https://github.com/PCIRCLE-AI/toonify-mcp/issues
- **GitHub**: https://github.com/PCIRCLE-AI/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.5.0 (2026-01-21)
- ✨ **Обновления SDK и инструментов** - MCP SDK, tokenizer и YAML обновлены
- ✨ Миграция на Jest 30 с SWC-обработкой TypeScript ESM
- 🔒 Исправления безопасности через npm audit

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