toonify-mcp 0.2.3 → 0.3.1

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) | [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 プラグインによる構造化データの自動トークン最適化。
+透過的な 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.ko.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 플러그인입니다.
+투명한 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 Docs**: https://code.claude.com/docs/mcp
+- **TOON Format**: https://github.com/toon-format/toon
+
+## 기여
+
+기여를 환영합니다! 가이드라인은 [CONTRIBUTING.md](CONTRIBUTING.md)를 참조하세요.
+
+## 라이선스
+
+MIT License - [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) | [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 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)