TOON Context Mcp Server

TOON Context MCP Server

An MCP (Model Context Protocol) server that automatically provides TOON-format context to coding agents, enabling transparent 30-60% token reduction for structured data without any workflow changes.

What Is This?

This MCP server intercepts file requests from coding agents and automatically converts data files to TOON format when beneficial. When you reference a JSON file, the server:

1. Analyzes the data structure
2. Converts to TOON if it saves tokens (typically 30-60% for tabular data)
3. Caches the TOON version for future use
4. Falls back to original format if TOON isn't beneficial

The magic? You never think about it. Reference files normally, get automatic token optimization.

Quick Start

1. Install

cd toon-context-mcp
./setup.sh

Or manually:

cd toon-context-mcp
npm install
npm run build

2. Configure Your MCP Client

For Cline (VSCode Extension)

Add to your Cline MCP configuration:

{
  "mcpServers": {
    "toon-context": {
      "command": "node",
      "args": ["/absolute/path/to/toon-context-mcp/build/index.js"],
      "env": {
        "TOON_THRESHOLD": "0.7",
        "AUTO_CONVERT": "true"
      }
    }
  }
}

For Zed Editor

Add to ~/.config/zed/settings.json:

{
  "context_servers": {
    "toon-context": {
      "command": "node",
      "args": ["/absolute/path/to/toon-context-mcp/build/index.js"]
    }
  }
}

For Other MCP Clients

The server follows the standard MCP protocol. Use:

• Command: node
• Args: ["/path/to/toon-context-mcp/build/index.js"]
• Transport: stdio

3. Test It

# Interactive testing tool
cd toon-context-mcp
npm run inspector

# Or run the test suite
cd ..
./TEST_MCP_SERVER.sh

4. Use It

Just use your coding agent normally! When you reference a data file:

"Analyze data/users.json and find inactive users"

The server automatically optimizes it to TOON if beneficial, saving you 30-60% tokens transparently.

Example: Real Token Savings

Before (JSON - 220 tokens):

{
  "users": [
    { "id": 1, "name": "Alice", "email": "alice@example.com", "role": "admin", "status": "active" },
    { "id": 2, "name": "Bob", "email": "bob@example.com", "role": "user", "status": "active" },
    ...
  ]
}

After (TOON - 84 tokens, 61.8% savings):

users[5]{id,name,email,role,status,created}:
  1,Alice Johnson,alice@example.com,admin,active,2024-01-15
  2,Bob Smith,bob@example.com,user,active,2024-02-20
  ...

Your workflow: No change. The server handles everything automatically.

How It Works

Smart Format Selection

The server analyzes each file and chooses the optimal format:

| Data Structure | Format | Reason | |----------------|--------|--------| | Uniform arrays of objects | TOON | 30-60% token savings | | Pure flat tables | CSV | Most efficient for simple tables | | Deeply nested (≥4 levels) | JSON | Better for complex structures | | Non-uniform data | JSON | More flexible format |

Automatic Caching

• First access: Analyzes and converts file, creates .toon file
• Subsequent access: Returns cached .toon file (if up-to-date)
• File modified: Automatically re-converts when source changes

File Exclusions

System files are automatically excluded:

• package.json, tsconfig.json, configuration files
• IDE settings files
• Lock files

MCP Tools

The server provides 4 MCP tools:

1. getoptimizedfile_context

Main tool for transparent optimization.

Returns the optimized file content (TOON if beneficial, original otherwise) with token savings statistics.

2. analyzedataefficiency

Analyze if TOON conversion would be beneficial.

Returns detailed metrics about data structure and estimated token savings.

3. batchconvertdirectory

Convert all eligible files in a directory.

Processes multiple files at once and returns conversion summary.

4. getconversionmetrics

Get detailed metrics comparing formats.

Provides token comparison without actually converting.

See [MCPSERVER.md](MCPSERVER.md) for detailed tool documentation.

Configuration

Environment Variables

Set these in your MCP client configuration:

| Variable | Default | Description | |----------|---------|-------------| | TOON_THRESHOLD | 0.7 | Minimum tabular eligibility (0-1) for TOON conversion | | AUTO_CONVERT | true | Whether to automatically convert files | | CACHE_DIR | ./.toon-cache | Directory for caching TOON files |

Threshold Guidelines

• 0.5-0.6: Aggressive (may convert mixed data)
• 0.7 (default): Balanced compromise
• 0.8-0.9: Conservative (only highly uniform data)
• 1.0: Strict (only 100% uniform arrays)

Testing

Run Test Suite

./TEST_MCP_SERVER.sh

Runs 17 tests covering:

• Data analysis accuracy
• File optimization
• Caching behavior
• Token savings calculation
• File exclusions

Interactive Inspector

cd toon-context-mcp
npm run inspector

Test the server tools interactively with your own files.

Performance

| Metric | Value | |--------|-------| | Conversion time | 10-50ms for typical JSON files | | Cache lookup | <1ms for cached TOON files | | Memory usage | Minimal (streaming not required) | | Token savings | 30-60% for uniform tabular data |

Real-World Results

From testing with sample data:

| File | Original Tokens | TOON Tokens | Savings | |------|-----------------|-------------|---------| | users.json (5 items) | 220 | 84 | 61.8% | | users.json (100 items) | 3,171 | 1,245 | 60.7% | | products.json (50 items) | 1,856 | 798 | 57.0% |

Project Structure

toon-context-mcp/
├── src/
│   ├── index.ts           # Main MCP server
│   ├── inspector.ts       # Interactive testing tool
│   ├── file-handler.ts    # File operations & conversion logic
│   ├── data-analyzer.ts   # Data structure analysis
│   └── toon-utils.ts      # TOON encoding/decoding
├── build/                 # Compiled JavaScript
├── examples/              # Test data
├── config/                # Example configurations
├── setup.sh               # Setup script
├── README.md              # Server documentation
└── package.json           # Dependencies

Use Cases

Perfect For

✅ Uniform arrays of objects - Same fields, primitive values ✅ Large tabular datasets - User lists, product catalogs, analytics data ✅ API responses - Consistent structured data ✅ Database exports - Table-like data structures

Not Ideal For

❌ Deeply nested objects - Complex hierarchical data ❌ Non-uniform data - Mixed structures ❌ Small datasets - Overhead not worth it (<10 items) ❌ Configuration files - Already excluded automatically

Troubleshooting

Server Not Starting

cd toon-context-mcp
rm -rf node_modules package-lock.json
npm install
npm run build

Files Not Converting

1. Check threshold: TOON_THRESHOLD=0.7
2. Analyze file: npm run inspector → option 2
3. Verify data is uniform (≥70% tabular)
4. Check if file is excluded (system file)

Cached Files Out of Date

Cache automatically invalidates when source files change. To force refresh:

rm path/to/file.toon

Agent Not Using Server

1. Verify MCP configuration is correct
2. Check server path is absolute
3. Restart the MCP client
4. Check server logs (stderr)

Documentation

• [MCPSERVER.md](MCPSERVER.md) - Detailed MCP server guide with examples
• [toon-context-mcp/README.md](toon-context-mcp/README.md) - Technical documentation
• TOON Format Spec - Official TOON specification
• Model Context Protocol - MCP specification

Why TOON?

TOON (Token-Oriented Object Notation) is a format optimized for LLM token efficiency. For uniform tabular data, it eliminates repetitive keys, reducing token count by 30-60% compared to JSON.

Key Benefits:

• 📉 Lower costs - Fewer tokens = lower API costs
• 🚀 Longer context - Fit more data in context window
• ⚡ Faster responses - Less data to process
• 🧠 Better performance - More efficient data representation

License

MIT License - See [LICENSE](LICENSE) file

Acknowledgments

• TOON Format by Johann Schopplich
• Model Context Protocol by Anthropic
• Built for integration with Factory.ai Droid and other MCP-compatible tools

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: jellyjamin
• Source: jellyjamin/TOON-context-mcp-server
• License: MIT

Install and usage instructions live in the source repository linked above.