# TOON Context Mcp Server

> MCP server for transparent TOON format optimization. Automatically converts data files to 30-60% more token-efficient format for coding agents with smart analysis and caching.

- **Type:** MCP server
- **Install:** `agentstack add mcp-jellyjamin-toon-context-mcp-server`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [jellyjamin](https://agentstack.voostack.com/s/jellyjamin)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [jellyjamin](https://github.com/jellyjamin)
- **Source:** https://github.com/jellyjamin/TOON-context-mcp-server

## Install

```sh
agentstack add mcp-jellyjamin-toon-context-mcp-server
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/toon-format/toon) 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

```bash
cd toon-context-mcp
./setup.sh
```

Or manually:
```bash
cd toon-context-mcp
npm install
npm run build
```

### 2. Configure Your MCP Client

#### For Cline (VSCode Extension)

Add to your Cline MCP configuration:

```json
{
  "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`:

```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

```bash
# 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):**
```json
{
  "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. 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 [MCP_SERVER.md](MCP_SERVER.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

```bash
./TEST_MCP_SERVER.sh
```

Runs 17 tests covering:
- Data analysis accuracy
- File optimization
- Caching behavior
- Token savings calculation
- File exclusions

### Interactive Inspector

```bash
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

```bash
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:

```bash
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

- **[MCP_SERVER.md](MCP_SERVER.md)** - Detailed MCP server guide with examples
- **[toon-context-mcp/README.md](toon-context-mcp/README.md)** - Technical documentation
- **[TOON Format Spec](https://github.com/toon-format/spec)** - Official TOON specification
- **[Model Context Protocol](https://github.com/modelcontextprotocol)** - 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](https://github.com/toon-format/toon) by Johann Schopplich
- [Model Context Protocol](https://github.com/modelcontextprotocol) by Anthropic
- Built for integration with [Factory.ai Droid](https://factory.ai/) 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](https://github.com/jellyjamin)
- **Source:** [jellyjamin/TOON-context-mcp-server](https://github.com/jellyjamin/TOON-context-mcp-server)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-jellyjamin-toon-context-mcp-server
- Seller: https://agentstack.voostack.com/s/jellyjamin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.