English | 繁體中文 | 日本語 | Español | Français | Deutsch | 한국어 | Русский | Português | Tiếng Việt | Bahasa Indonesia
Toonify MCP is an MCP server and Claude Code plugin for automatic token optimization in structured data and source-code workflows.
It is designed for teams that regularly send large JSON / CSV / YAML payloads or TypeScript / Python / Go source files into model context and want lower token usage without changing day-to-day workflow.
- Structured data: 25-66% token reduction (typically ~48%)
- Source code: 20-48% reduction on TypeScript / Python / Go
- Docs and setup guides: https://toonify.pcircle.ai/
✨ Pipeline Architecture + Code Compression!
- ✅ Pipeline engine — modular Detector → Router → Compressor → Evaluator architecture
- ✅ Code compression — TypeScript (37%), Python (48%), Go (32%) savings via heuristic-based comment/whitespace removal
- ✅ 6 compression layers — from safe (blank lines, inline comments) to aggressive (import summarization, repetitive pattern collapse)
- ✅ Hook upgraded — PostToolUse hook now compresses source code in addition to structured data
- ✅ Extensible design — add new formats by implementing a single
Compressorinterface - ✅ Full backwards compatibility — all external APIs unchanged
- ✅ 196 tests (up from 157), comprehensive code review passed
- 25-66% Token Reduction (typically ~48%) for JSON, CSV, YAML data
- 20-48% Code Compression for TypeScript, Python, Go source code
- Pipeline Architecture - Extensible Detector → Compressor → Evaluator engine
- Multilingual Support - Accurate token counting for 15+ languages
- Enhanced Caching - LRU cache with TTL expiration and optional disk persistence
- 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)
- Built-in Metrics - Track token savings locally
- Silent Fallback - Never breaks your workflow
- Security Hardened - Input size limits, path validation, safe regex, atomic writes
Install directly from the GitHub repository (no npm publish required):
# 1. Download the repository
git clone https://github.com/PCIRCLE-AI/toonify-mcp.git
cd toonify-mcp
# 2. Install deps and build
npm install
npm run build
# 3. Install globally from local source
npm install -g .One-click installation through Claude Marketplaces:
Browse to Claude Marketplaces in Claude Code and install toonify-mcp with one click when marketplace distribution is available for your environment.
Automatic token optimization with zero manual calls:
Prerequisite: complete Option A or Option B so the toonify-mcp binary is available.
# 1. Add as plugin (automatic mode)
claude plugin add toonify-mcp
# 2. Verify installation
claude plugin list
# Should show: toonify-mcp ✓That's it! The PostToolUse hook will now automatically intercept and optimize structured data from Read, Grep, and other file tools.
For explicit control or non-Claude Code MCP clients:
Prerequisite: complete Option A or Option B so the toonify-mcp binary is available.
# 1. Register as MCP server
claude mcp add toonify -- toonify-mcp
# 2. Verify
claude mcp list
# Should show: toonify: toonify-mcp - ✓ ConnectedThen call tools explicitly:
claude mcp call toonify optimize_content '{"content": "..."}'
claude mcp call toonify get_stats '{}'User: Read large JSON file
↓
Claude Code calls Read tool
↓
PostToolUse hook intercepts result
↓
Pipeline: Detect → Route → Compress → Evaluate
↓
JSON/CSV/YAML → TOON format (25-66% savings)
Source code → comment/whitespace removal (20-48% savings)
↓
Optimized content sent to Claude API ✨
User: explicitly calls mcp__toonify__optimize_content
↓
Content converted to TOON format
↓
Returns optimized result
Create ~/.claude/toonify-config.json (optional):
{
"enabled": true,
"minTokensThreshold": 50,
"minSavingsThreshold": 30,
"skipToolPatterns": ["Bash", "Write", "Edit"]
}- enabled: Enable/disable automatic optimization (default:
true) - minTokensThreshold: Minimum tokens before optimization (default:
50) - minSavingsThreshold: Minimum savings percentage required (default:
30%) - skipToolPatterns: Tools to never optimize (default:
["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 # Show optimization stats in output{
"products": [
{"id": 101, "name": "Laptop Pro", "price": 1299},
{"id": 102, "name": "Magic Mouse", "price": 79}
]
}[TOON-JSON]
products[2]{id,name,price}:
101,Laptop Pro,1299
102,Magic Mouse,79
Automatically applied in Plugin mode - no manual calls needed!
The PostToolUse hook automatically optimizes when:
- ✅ Content is valid JSON, CSV, YAML, or source code (TS/Py/Go)
- ✅ Content size ≥
minTokensThreshold(default: 50 tokens) - ✅ Estimated savings ≥ threshold (30% for structured data, 10% for code)
- ✅ Tool is NOT in
skipToolPatterns(e.g., not Bash/Write/Edit)
# In Plugin mode
claude mcp call toonify get_stats '{}'
# Or check Claude Code output for stats (if TOONIFY_SHOW_STATS=true)Toonify v0.5.0+ includes an enhanced LRU cache with TTL expiration:
# Get cache statistics
claude mcp call toonify get_cache_stats '{}'
# Clear all cached results
claude mcp call toonify clear_cache '{}'
# Clean up expired entries
claude mcp call toonify cleanup_expired_cache '{}'Cache benefits:
- ✅ 50-500x faster on cache hits (0.1ms vs 5-50ms)
- ✅ Avoids re-optimizing identical content
- ✅ Optional disk persistence for cross-session reuse
- ✅ Automatic LRU eviction when full
- ✅ TTL expiration (default: 1 hour)
See docs/CACHE.md for detailed cache documentation.
# 1. Check plugin is installed
claude plugin list | grep toonify
# 2. Check configuration
cat ~/.claude/toonify-config.json
# 3. Enable stats to see optimization attempts
export TOONIFY_SHOW_STATS=true- Check
minTokensThreshold- content might be too small - Check
minSavingsThreshold- savings might be < 30% - Check
skipToolPatterns- tool might be in skip list - Verify content is valid JSON/CSV/YAML or recognized source code
- Reduce
minTokensThresholdto optimize more aggressively - Increase
minSavingsThresholdto skip marginal optimizations - Add more tools to
skipToolPatternsif needed
| Feature | Plugin Mode | MCP Server Mode |
|---|---|---|
| Activation | Automatic (PostToolUse) | Manual (call tool) |
| Compatibility | Claude Code only | Any MCP client |
| Configuration | Plugin config file | MCP tools |
| Performance | Zero overhead | Call overhead |
| Use Case | Daily workflow | Explicit control |
Recommendation: Use Plugin mode for automatic optimization. Use MCP Server mode for explicit control or other MCP clients.
claude plugin remove toonify-mcp
rm ~/.claude/toonify-config.jsonclaude mcp remove toonifynpm uninstall -g toonify-mcp- Docs: https://toonify.pcircle.ai/
- GitHub: https://github.com/PCIRCLE-AI/toonify-mcp
- Issues: https://github.com/PCIRCLE-AI/toonify-mcp/issues
- MCP Docs: https://code.claude.com/docs/mcp
- TOON Format: https://github.com/toon-format/toon
Contributions welcome! Please see CONTRIBUTING.md for guidelines.
For setup help, bug reports, and commercial contact paths, see SUPPORT.md.
Please report vulnerabilities privately as described in SECURITY.md.
MIT License - see LICENSE
For release history, see CHANGELOG.md.