🎯 Toonify MCP

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/

What's New in v0.6.0

✨ 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 Compressor interface
✅ Full backwards compatibility — all external APIs unchanged
✅ 196 tests (up from 157), comprehensive code review passed

Features

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

Installation

Option A: Download from GitHub (Recommended) 🌟

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 .

Option B: Install from Claude Marketplaces (if available) 🌟

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.

Option C: Claude Code Plugin (Recommended) ⭐

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.

Option D: MCP Server (Manual mode)

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 - ✓ Connected

Then call tools explicitly:

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

How It Works

Plugin Mode (Automatic)

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 ✨

MCP Server Mode (Manual)

User: explicitly calls mcp__toonify__optimize_content
  ↓
Content converted to TOON format
  ↓
Returns optimized result

Configuration

Create ~/.claude/toonify-config.json (optional):

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

Options

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"])

Environment Variables

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

Examples

Before Optimization (142 tokens)

{
  "products": [
    {"id": 101, "name": "Laptop Pro", "price": 1299},
    {"id": 102, "name": "Magic Mouse", "price": 79}
  ]
}

After Optimization (57 tokens, -60%)

[TOON-JSON]
products[2]{id,name,price}:
  101,Laptop Pro,1299
  102,Magic Mouse,79

Automatically applied in Plugin mode - no manual calls needed!

Usage Tips

When Does Auto-Optimization Trigger?

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)

View Optimization Stats

# In Plugin mode
claude mcp call toonify get_stats '{}'

# Or check Claude Code output for stats (if TOONIFY_SHOW_STATS=true)

Cache Management

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.

Troubleshooting

Hook Not Triggering

# 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

Optimization Not Applied

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

Performance Issues

Reduce minTokensThreshold to optimize more aggressively
Increase minSavingsThreshold to skip marginal optimizations
Add more tools to skipToolPatterns if needed

Comparison: Plugin vs MCP Server

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.

Uninstall

Plugin Mode

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

MCP Server Mode

claude mcp remove toonify

Package

npm uninstall -g toonify-mcp

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

Support

For setup help, bug reports, and commercial contact paths, see SUPPORT.md.

Security

Please report vulnerabilities privately as described in SECURITY.md.

License

MIT License - see LICENSE

For release history, see CHANGELOG.md.

toonify-mcp