jellyjamin/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:

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. get_optimized_file_context

Main tool for transparent optimization.

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

2. analyze_data_efficiency

Analyze if TOON conversion would be beneficial.

Returns detailed metrics about data structure and estimated token savings.

3. batch_convert_directory

Convert all eligible files in a directory.

Processes multiple files at once and returns conversion summary.

4. get_conversion_metrics

Get detailed metrics comparing formats.

Provides token comparison without actually converting.

See for detailed tool documentation.

Configuration

Environment Variables

Set these in your MCP client configuration:

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

Real-World Results

From testing with sample data:

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

• - Detailed MCP server guide with examples
• - 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 file

Acknowledgments

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