Skip to content

README.ja.md

Latest commit

 

History

History
277 lines (199 loc) · 9.57 KB

README.ja.md

File metadata and controls

277 lines (199 loc) · 9.57 KB

🎯 Toonify MCP

English | 繁體中文 | 日本語 | Español | Français | Deutsch | 한국어 | Русский | Português | Tiếng Việt | Bahasa Indonesia

MCP サーバー + Claude Code プラグインによる構造化データおよびソースコードの自動トークン最適化。 JSON/CSV/YAML で 25-66%、TypeScript/Python/Go ソースコードで 20-48% のトークン削減を Pipeline アーキテクチャで実現します。

v0.6.0 の新機能

✨ Pipeline アーキテクチャ + コード圧縮！

  • ✅ Pipeline エンジン — モジュラー Detector → Router → Compressor → Evaluator アーキテクチャ
  • ✅ コード圧縮 — TypeScript（37%）、Python（48%）、Go（32%）のヒューリスティックベース圧縮
  • ✅ 6 圧縮レイヤー — 空行マージ、インラインコメント削除、importパス短縮、import要約、繰り返しパターン折りたたみ
  • ✅ フック強化 — PostToolUse フックが構造化データに加えソースコードも圧縮
  • ✅ 拡張可能な設計 — Compressor インターフェースを実装するだけで新フォーマットに対応
  • ✅ 完全な後方互換性 — すべての外部 API は変更なし
  • ✅ 196 テスト（157 から増加）、包括的なコードレビュー合格

機能

  • 25-66% のトークン削減（通常 約48%）- JSON、CSV、YAML データに対応
  • 20-48% のコード圧縮 - TypeScript、Python、Go ソースコードに対応
  • Pipeline アーキテクチャ - 拡張可能な Detector → Compressor → Evaluator エンジン
  • 多言語サポート - 15 以上の言語の正確なトークンカウント
  • 完全自動 - PostToolUse フックがツール結果を傍受
  • 設定不要 - 賢明なデフォルト設定で開箱即用
  • デュアルモード - プラグイン（自動）または MCP サーバー（手動）として動作
  • 組み込みメトリクス - トークン節約をローカルで追跡
  • サイレントフォールバック - ワークフローを中断しません

インストール

オプション A：GitHub からダウンロード（推奨）🌟

GitHub リポジトリから直接インストール（npm 公開は不要）：

# 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：Claude Marketplaces からインストール（利用可能な場合）🌟

ワンクリックインストール：

Claude Code で Claude Marketplaces を開き、環境で marketplace distribution が利用可能な場合は toonify-mcp をワンクリックでインストールできます。

オプション C：Claude Code プラグイン（推奨）⭐

手動呼び出し不要の自動トークン最適化：

前提条件：オプション A または B を完了し、toonify-mcp バイナリを利用可能にしてください。

# 1. プラグインとして追加（自動モード）
claude plugin add toonify-mcp

# 2. インストールを確認
claude plugin list
# 表示されるはず：toonify-mcp ✓

これで完了！ PostToolUse フックが Read、Grep、その他のファイルツールからの構造化データを自動的に傍受して最適化します。

オプション D：MCP サーバー（手動モード）

明示的な制御または非 Claude Code MCP クライアント用：

前提条件：オプション A または B を完了し、toonify-mcp バイナリを利用可能にしてください。

# 1. MCP サーバーとして登録
claude mcp add toonify -- toonify-mcp

# 2. 確認
claude mcp list
# 表示されるはず：toonify: toonify-mcp - ✓ Connected

次にツールを明示的に呼び出します：

claude mcp call toonify optimize_content '{"content": "..."}'
claude mcp call toonify get_stats '{}'

動作原理

プラグインモード（自動）

ユーザー：大きな JSON ファイルを読む
  ↓
Claude Code が Read ツールを呼び出す
  ↓
PostToolUse フックが結果を傍受
  ↓
フックが JSON を検出し、TOON に変換
  ↓
最適化されたコンテンツを Claude API に送信
  ↓
25-66%（通常 約48%）のトークン削減を達成 ✨

MCP サーバーモード（手動）

ユーザー：mcp__toonify__optimize_content を明示的に呼び出す
  ↓
コンテンツを TOON フォーマットに変換
  ↓
最適化された結果を返す

設定

~/.claude/toonify-config.json を作成（オプション）：

{
  "enabled": true,
  "minTokensThreshold": 50,
  "minSavingsThreshold": 30,
  "skipToolPatterns": ["Bash", "Write", "Edit"]
}

オプション

  • enabled：自動最適化を有効/無効にする（デフォルト：true）
  • minTokensThreshold：最適化前の最小トークン数（デフォルト：50）
  • minSavingsThreshold：必要な最小節約率（デフォルト：30%）
  • skipToolPatterns：最適化しないツール（デフォルト：["Bash", "Write", "Edit"]）

環境変数

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 トークン）

{
  "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 ではない）

最適化統計を表示

# プラグインモードで
claude mcp call toonify get_stats '{}'

# または Claude Code 出力の統計を確認（TOONIFY_SHOW_STATS=true の場合）

トラブルシューティング

フックがトリガーされない

# 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 サーバーモードを使用。

アンインストール

プラグインモード

claude plugin remove toonify-mcp
rm ~/.claude/toonify-config.json

MCP サーバーモード

claude mcp remove toonify

パッケージ

npm uninstall -g toonify-mcp

リンク

貢献

貢献を歓迎します！ガイドラインについては CONTRIBUTING.md を参照してください。

サポート

セットアップ支援、バグ報告、商用連絡先については SUPPORT.md を参照してください。

セキュリティ

脆弱性は SECURITY.md に記載された方法で非公開で報告してください。

ライセンス

MIT ライセンス - 詳細は LICENSE を参照

リリース履歴は CHANGELOG.md を参照してください。