toonify-mcp 0.2.3 → 0.3.0

package/README.ja.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)**
+
+MCP サーバー + Claude Code プラグインによる構造化データの自動トークン最適化。
+透過的な TOON フォーマット変換により、**データ構造に応じて Claude API トークン使用量を 30-65% 削減**し、構造化データでは一般的に **50-55%** の節約を実現します。
+
+## v0.3.0 の新機能
+
+✨ **多言語トークン最適化！**
+- ✅ 15 以上の言語（中国語、日本語、韓国語、スペイン語、アラビア語など）の正確なトークンカウント
+- ✅ 言語を考慮したトークン倍率（中国語 2 倍、日本語 2.5 倍、アラビア語 3 倍）
+- ✅ 混合言語テキストの自動検出をサポート
+- ✅ 実際のベンチマークに基づく最適化精度の向上
+- ✅ データに裏付けられたトークン節約の主張（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 サーバー（手動モード）
+
+**明示的な制御または非 Claude Code 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 ドキュメント**：https://code.claude.com/docs/mcp
+- **TOON フォーマット**：https://github.com/toon-format/toon
+
+## 貢献
+
+貢献を歓迎します！ガイドラインについては [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
+
+## ライセンス
+
+MIT ライセンス - 詳細は [LICENSE](LICENSE) を参照
+
+## 変更履歴
+
+### v0.3.0（2025-12-26）
+- ✨ **多言語トークン最適化** - 15 以上の言語の正確なカウント
+- ✨ 言語を考慮したトークン倍率（中国語 2 倍、日本語 2.5 倍、アラビア語 3 倍など）
+- ✨ 混合言語テキストの検出と最適化
+- ✨ 実際の統計を使用した包括的なベンチマークテスト
+- 📊 データに裏付けられたトークン節約の主張（30-65% の範囲、通常 50-55%）
+- ✅ 多言語エッジケースを含む 75 以上のテスト合格
+- 📝 多言語 README バージョン
+
+### v0.2.0（2025-12-25）
+- ✨ PostToolUse フックによる Claude Code プラグインサポートの追加
+- ✨ 自動トークン最適化（手動呼び出し不要）
+- ✨ プラグイン設定システム
+- ✨ デュアルモード：プラグイン（自動）+ MCP サーバー（手動）
+- 📝 包括的なドキュメント更新
+
+### v0.1.1（2024-12-24）
+- 🐛 バグ修正と改善
+- 📝 ドキュメント更新
+
+### v0.1.0（2024-12-24）
+- 🎉 初回リリース
+- ✨ MCP サーバー実装
+- ✨ TOON フォーマット最適化
+- ✨ 組み込みメトリクス追跡

package/README.md

@@ -1,21 +1,23 @@
 # 🎯 Toonify MCP
 
-**[English](README.md) | [繁體中文](README.zh-TW.md)**
+**[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)**
 
 MCP server + Claude Code Plugin providing automatic token optimization for structured data.
-Reduces Claude API token usage by **60%+ on average** through transparent TOON format conversion.
+Reduces Claude API token usage by **30-65% depending on data structure** through transparent TOON format conversion, with typical savings of **50-55%** for structured data.
 
-## What's New in v0.2.0
+## What's New in v0.3.0
 
-✨ **Now a full Claude Code Plugin!**
-- ✅ Automatic PostToolUse hook interception
-- ✅ Zero manual calls needed
-- ✅ Transparent optimization
-- ✅ Still works as standalone MCP server
+✨ **Multilingual Token Optimization!**
+- ✅ Accurate token counting for 15+ languages (Chinese, Japanese, Korean, Spanish, Arabic, etc.)
+- ✅ Language-aware token multipliers (2x for Chinese, 2.5x for Japanese, 3x for Arabic)
+- ✅ Mixed-language text support with automatic detection
+- ✅ Improved optimization accuracy based on real benchmarks
+- ✅ Data-backed token savings claims (30-65% range, typically 50-55%)
 
 ## Features
 
-- **60%+ Token Reduction** for JSON, CSV, YAML data
+- **30-65% Token Reduction** (typically 50-55%) for JSON, CSV, YAML data
+- **Multilingual Support** - Accurate token counting for 15+ languages
 - **Fully Automatic** - PostToolUse hook intercepts tool results
 - **Zero Configuration** - Works out of the box with sensible defaults
 - **Dual Mode** - Works as Plugin (auto) or MCP Server (manual)
@@ -79,7 +81,7 @@ Hook detects JSON, converts to TOON
   ↓
 Optimized content sent to Claude API
   ↓
-60% token reduction achieved ✨
+50-55% typical token reduction achieved ✨
 ```
 
 ### MCP Server Mode (Manual)
@@ -241,6 +243,15 @@ MIT License - see [LICENSE](LICENSE)
 
 ## Changelog
 
+### v0.3.0 (2025-12-26)
+- ✨ **Multilingual token optimization** - accurate counting for 15+ languages
+- ✨ Language-aware token multipliers (2x Chinese, 2.5x Japanese, 3x Arabic, etc.)
+- ✨ Mixed-language text detection and optimization
+- ✨ Comprehensive benchmark testing with real statistics
+- 📊 Data-backed token savings claims (30-65% range, typically 50-55%)
+- ✅ 75+ tests passing, including multilingual edge cases
+- 📝 Multilingual README versions
+
 ### v0.2.0 (2025-12-25)
 - ✨ Added Claude Code Plugin support with PostToolUse hook
 - ✨ Automatic token optimization (no manual calls needed)

package/README.vi.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)**
+
+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.
+
+## Tính năng mới trong v0.3.0
+
+✨ **Tối ưu hóa token đa ngôn ngữ!**
+- ✅ Đếm token chính xác cho hơn 15 ngôn ngữ (Trung, Nhật, Hàn, Tây Ban Nha, Ả Rập, v.v.)
+- ✅ Hệ số nhân token nhận biết ngôn ngữ (2x cho tiếng Trung, 2.5x cho tiếng Nhật, 3x cho tiếng Ả Rập)
+- ✅ Hỗ trợ phát hiện tự động văn bản hỗn hợp nhiều ngôn ngữ
+- ✅ Cải thiện độ chính xác tối ưu hóa dựa trên kiểm tra chuẩn thực tế
+- ✅ Tuyên bố tiết kiệm token được hỗ trợ bởi dữ liệu (phạm vi 30-65%, thường 50-55%)
+
+## Tính năng
+
+- **Giảm 30-65% token** (thường 50-55%) cho dữ liệu JSON, CSV, YAML
+- **Hỗ trợ đa ngôn ngữ** - Đếm token chính xác cho hơn 15 ngôn ngữ
+- **Hoàn toàn tự động** - Hook PostToolUse chặn kết quả công cụ
+- **Không cần cấu hình** - Hoạt động ngay lập tức với các giá trị mặc định hợp lý
+- **Chế độ kép** - Hoạt động như plugin (tự động) hoặc máy chủ MCP (thủ công)
+- **Chỉ số tích hợp** - Theo dõi tiết kiệm token cục bộ
+- **Dự phòng im lặng** - Không bao giờ làm gián đoạn quy trình làm việc của bạn
+
+## Cài đặt
+
+### Tùy chọn A: Plugin Claude Code (Khuyến nghị) ⭐
+
+**Tối ưu hóa token tự động không cần gọi thủ công:**
+
+```bash
+# 1. Cài đặt toàn cục
+npm install -g toonify-mcp
+
+# 2. Thêm làm plugin (chế độ tự động)
+claude plugin add toonify-mcp
+
+# 3. Xác minh cài đặt
+claude plugin list
+# Nên hiển thị: toonify-mcp ✓
+```
+
+**Xong! ** Hook PostToolUse bây giờ sẽ tự động chặn và tối ưu hóa dữ liệu có cấu trúc từ Read, Grep và các công cụ tệp khác.
+
+### Tùy chọn B: Máy chủ MCP (chế độ thủ công)
+
+**Cho kiểm soát rõ ràng hoặc các máy khách MCP không phải Claude Code:**
+
+```bash
+# 1. Cài đặt toàn cục
+npm install -g toonify-mcp
+
+# 2. Đăng ký làm máy chủ MCP
+claude mcp add toonify -- toonify-mcp
+
+# 3. Xác minh
+claude mcp list
+# Nên hiển thị: toonify: toonify-mcp - ✓ Connected
+```
+
+Sau đó gọi các công cụ rõ ràng:
+```bash
+claude mcp call toonify optimize_content '{"content": "..."}'
+claude mcp call toonify get_stats '{}'
+```
+
+## Cách hoạt động
+
+### Chế độ plugin (tự động)
+
+```
+Người dùng: Đọc tệp JSON lớn
+  ↓
+Claude Code gọi công cụ Read
+  ↓
+Hook PostToolUse chặn kết quả
+  ↓
+Hook phát hiện JSON, chuyển đổi sang TOON
+  ↓
+Nội dung đã tối ưu hóa được gửi đến Claude API
+  ↓
+Đạt được mức giảm token điển hình 50-55% ✨
+```
+
+### Chế độ máy chủ MCP (thủ công)
+
+```
+Người dùng: Gọi rõ ràng mcp__toonify__optimize_content
+  ↓
+Nội dung được chuyển đổi sang định dạng TOON
+  ↓
+Trả về kết quả đã tối ưu hóa
+```
+
+## Cấu hình
+
+Tạo `~/.claude/toonify-config.json` (tùy chọn):
+
+```json
+{
+  "enabled": true,
+  "minTokensThreshold": 50,
+  "minSavingsThreshold": 30,
+  "skipToolPatterns": ["Bash", "Write", "Edit"]
+}
+```
+
+### Tùy chọn
+
+- **enabled**: Bật/tắt tối ưu hóa tự động (mặc định: `true`)
+- **minTokensThreshold**: Token tối thiểu trước khi tối ưu hóa (mặc định: `50`)
+- **minSavingsThreshold**: Phần trăm tiết kiệm tối thiểu yêu cầu (mặc định: `30%`)
+- **skipToolPatterns**: Công cụ không bao giờ tối ưu hóa (mặc định: `["Bash", "Write", "Edit"]`)
+
+### Biến môi trường
+
+```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  # Hiển thị thống kê tối ưu hóa trong đầu ra
+```
+
+## Ví dụ
+
+### Trước khi tối ưu hóa (142 token)
+
+```json
+{
+  "products": [
+    {"id": 101, "name": "Laptop Pro", "price": 1299},
+    {"id": 102, "name": "Magic Mouse", "price": 79}
+  ]
+}
+```
+
+### Sau khi tối ưu hóa (57 token, -60%)
+
+```
+[TOON-JSON]
+products[2]{id,name,price}:
+  101,Laptop Pro,1299
+  102,Magic Mouse,79
+```
+
+**Tự động áp dụng ở chế độ plugin - không cần gọi thủ công!**
+
+## Mẹo sử dụng
+
+### Khi nào tối ưu hóa tự động được kích hoạt?
+
+Hook PostToolUse tự động tối ưu hóa khi:
+- ✅ Nội dung là JSON, CSV hoặc YAML hợp lệ
+- ✅ Kích thước nội dung ≥ `minTokensThreshold` (mặc định: 50 token)
+- ✅ Tiết kiệm ước tính ≥ `minSavingsThreshold` (mặc định: 30%)
+- ✅ Công cụ KHÔNG có trong `skipToolPatterns` (ví dụ: không phải Bash/Write/Edit)
+
+### Xem thống kê tối ưu hóa
+
+```bash
+# Ở chế độ plugin
+claude mcp call toonify get_stats '{}'
+
+# Hoặc kiểm tra đầu ra Claude Code để xem thống kê (nếu TOONIFY_SHOW_STATS=true)
+```
+
+## Khắc phục sự cố
+
+### Hook không kích hoạt
+
+```bash
+# 1. Kiểm tra plugin đã được cài đặt
+claude plugin list | grep toonify
+
+# 2. Kiểm tra cấu hình
+cat ~/.claude/toonify-config.json
+
+# 3. Bật thống kê để xem các lần thử tối ưu hóa
+export TOONIFY_SHOW_STATS=true
+```
+
+### Tối ưu hóa không được áp dụng
+
+- Kiểm tra `minTokensThreshold` - nội dung có thể quá nhỏ
+- Kiểm tra `minSavingsThreshold` - tiết kiệm có thể < 30%
+- Kiểm tra `skipToolPatterns` - công cụ có thể nằm trong danh sách bỏ qua
+- Xác minh nội dung là JSON/CSV/YAML hợp lệ
+
+### Vấn đề hiệu suất
+
+- Giảm `minTokensThreshold` để tối ưu hóa tích cực hơn
+- Tăng `minSavingsThreshold` để bỏ qua các tối ưu hóa biên
+- Thêm nhiều công cụ hơn vào `skipToolPatterns` nếu cần
+
+## So sánh: Plugin vs Máy chủ MCP
+
+| Tính năng | Chế độ Plugin | Chế độ Máy chủ MCP |
+|-----------|--------------|-------------------|
+| **Kích hoạt** | Tự động (PostToolUse) | Thủ công (gọi công cụ) |
+| **Tương thích** | Chỉ Claude Code | Bất kỳ máy khách MCP nào |
+| **Cấu hình** | Tệp cấu hình plugin | Công cụ MCP |
+| **Hiệu suất** | Không có chi phí | Chi phí gọi |
+| **Trường hợp sử dụng** | Quy trình làm việc hàng ngày | Kiểm soát rõ ràng |
+
+**Khuyến nghị**: Sử dụng chế độ plugin cho tối ưu hóa tự động. Sử dụng chế độ máy chủ MCP cho kiểm soát rõ ràng hoặc các máy khách MCP khác.
+
+## Gỡ cài đặt
+
+### Chế độ plugin
+```bash
+claude plugin remove toonify-mcp
+rm ~/.claude/toonify-config.json
+```
+
+### Chế độ máy chủ MCP
+```bash
+claude mcp remove toonify
+```
+
+### Gói
+```bash
+npm uninstall -g toonify-mcp
+```
+
+## Liên kết
+
+- **GitHub**: https://github.com/kevintseng/toonify-mcp
+- **Issues**: https://github.com/kevintseng/toonify-mcp/issues
+- **NPM**: https://www.npmjs.com/package/toonify-mcp
+- **Tài liệu MCP**: https://code.claude.com/docs/mcp
+- **Định dạng TOON**: https://github.com/toon-format/toon
+
+## Đóng góp
+
+Đóng góp được chào đón! Vui lòng xem [CONTRIBUTING.md](CONTRIBUTING.md) để biết hướng dẫn.
+
+## Giấy phép
+
+Giấy phép MIT - xem [LICENSE](LICENSE)
+
+## Nhật ký thay đổi
+
+### v0.3.0 (2025-12-26)
+- ✨ **Tối ưu hóa token đa ngôn ngữ** - đếm chính xác cho hơn 15 ngôn ngữ
+- ✨ Hệ số nhân token nhận biết ngôn ngữ (2x Trung, 2.5x Nhật, 3x Ả Rập, v.v.)
+- ✨ Phát hiện và tối ưu hóa văn bản hỗn hợp nhiều ngôn ngữ
+- ✨ Kiểm tra chuẩn toàn diện với thống kê thực tế
+- 📊 Tuyên bố tiết kiệm token được hỗ trợ bởi dữ liệu (phạm vi 30-65%, thường 50-55%)
+- ✅ Hơn 75 kiểm tra đã vượt qua, bao gồm các trường hợp biên đa ngôn ngữ
+- 📝 Các phiên bản README đa ngôn ngữ
+
+### v0.2.0 (2025-12-25)
+- ✨ Đã thêm hỗ trợ plugin Claude Code với hook PostToolUse
+- ✨ Tối ưu hóa token tự động (không cần gọi thủ công)
+- ✨ Hệ thống cấu hình plugin
+- ✨ Chế độ kép: Plugin (tự động) + Máy chủ MCP (thủ công)
+- 📝 Cập nhật tài liệu toàn diện
+
+### v0.1.1 (2024-12-24)
+- 🐛 Sửa lỗi và cải tiến
+- 📝 Cập nhật tài liệu
+
+### v0.1.0 (2024-12-24)
+- 🎉 Phát hành ban đầu
+- ✨ Triển khai máy chủ MCP
+- ✨ Tối ưu hóa định dạng TOON
+- ✨ Theo dõi chỉ số tích hợp