{"id":"960b6d76-216c-4275-9d96-b7d3244ef48e","slug":"toon-context-mcp-server","kind":"mcp","name":"TOON-context-mcp-server","summary":"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.","owner":"jellyjamin","repoUrl":"https://github.com/jellyjamin/TOON-context-mcp-server","license":"MIT","licenseTier":"permissive","trust":"community","stars":5,"match":null,"fewStars":false,"format":"mcp","createdAt":"2025-11-08T04:28:18.000Z","addedAt":"2026-10-21T08:08:04.069Z","logoUrl":"https://avatars.githubusercontent.com/u/75885147?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["cloud-infra","memory-knowledge","files-documents"],"tags":["context","json","llm"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-21T08:08:15.267Z","sample":false,"url":"https://conduits.dev/tools/toon-context-mcp-server","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# TOON Context MCP Server\n\nAn 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.\n\n## What Is This?\n\nThis 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:\n\n1. **Analyzes** the data structure\n2. **Converts** to TOON if it saves tokens (typically 30-60% for tabular data)\n3. **Caches** the TOON version for future use\n4. **Falls back** to original format if TOON isn't beneficial\n\n**The magic?** You never think about it. Reference files normally, get automatic token optimization.\n\n## Quick Start\n\n### 1. Install\n\n```bash\ncd toon-context-mcp\n./setup.sh\n```\n\nOr manually:\n```bash\ncd toon-context-mcp\nnpm install\nnpm run build\n```\n\n### 2. Configure Your MCP Client\n\n#### For Cline (VSCode Extension)\n\nAdd to your Cline MCP configuration:\n\n```json\n{\n  \"mcpServers\": {\n    \"toon-context\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/toon-context-mcp/build/index.js\"],\n      \"env\": {\n        \"TOON_THRESHOLD\": \"0.7\",\n        \"AUTO_CONVERT\": \"true\"\n      }\n    }\n  }\n}\n```\n\n#### For Zed Editor\n\nAdd to `~/.config/zed/settings.json`:\n\n```json\n{\n  \"context_servers\": {\n    \"toon-context\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/toon-context-mcp/build/index.js\"]\n    }\n  }\n}\n```\n\n#### For Other MCP Clients\n\nThe server follows the standard MCP protocol. Use:\n- **Command:** `node`\n- **Args:** `[\"/path/to/toon-context-mcp/build/index.js\"]`\n- **Transport:** stdio\n\n### 3. Test It\n\n```bash\n# Interactive testing tool\ncd toon-context-mcp\nnpm run inspector\n\n# Or run the test suite\ncd ..\n./TEST_MCP_SERVER.sh\n```\n\n### 4. Use It\n\nJust use your coding agent normally! When you reference a data file:\n\n```\n\"Analyze data/users.json and find inactive users\"\n```\n\nThe server automatically optimizes it to TOON if beneficial, saving you 30-60% tokens transparently.\n\n## Example: Real Token Savings\n\n**Before (JSON - 220 tokens):**\n```json\n{\n  \"users\": [\n    { \"id\": 1, \"name\": \"Alice\", \"email\": \"alice@example.com\", \"role\": \"admin\", \"status\": \"active\" },\n    { \"id\": 2, \"name\": \"Bob\", \"email\": \"bob@example.com\", \"role\": \"user\", \"status\": \"active\" },\n    ...\n  ]\n}\n```\n\n**After (TOON - 84 tokens, 61.8% savings):**\n```\nusers[5]{id,name,email,role,status,created}:\n  1,Alice Johnson,alice@example.com,admin,active,2024-01-15\n  2,Bob Smith,bob@example.com,user,active,2024-02-20\n  ...\n```\n\n**Your workflow:** No change. The server handles everything automatically.\n\n## How It Works\n\n### Smart Format Selection\n\nThe server analyzes each file and chooses the optimal format:\n\n| Data Structure | Format | Reason |\n|----------------|--------|--------|\n| Uniform arrays of objects | **TOON** | 30-60% token savings |\n| Pure flat tables | **CSV** | Most efficient for simple tables |\n| Deeply nested (≥4 levels) | **JSON** | Better for complex structures |\n| Non-uniform data | **JSON** | More flexible format |\n\n### Automatic Caching\n\n- **First access:** Analyzes and converts file, creates `.toon` file\n- **Subsequent access:** Returns cached `.toon` file (if up-to-date)\n- **File modified:** Automatically re-converts when source changes\n\n### File Exclusions\n\nSystem files are automatically excluded:\n- `package.json`, `tsconfig.json`, configuration files\n- IDE settings files\n- Lock files\n\n## MCP Tools\n\nThe server provides 4 MCP tools:\n\n### 1. get_optimized_file_context\n\n**Main tool for transparent optimization.**\n\nReturns the optimized file content (TOON if beneficial, original otherwise) with token savings statistics.\n\n### 2. analyze_data_efficiency\n\n**Analyze if TOON conversion would be beneficial.**\n\nReturns detailed metrics about data structure and estimated token savings.\n\n### 3. batch_convert_directory\n\n**Convert all eligible files in a directory.**\n\nProcesses multiple files at once and returns conversion summary.\n\n### 4. get_conversion_metrics\n\n**Get detailed metrics comparing formats.**\n\nProvides token comparison without actually converting.\n\nSee [MCP_SERVER.md](MCP_SERVER.md) for detailed tool documentation.\n\n## Configuration\n\n### Environment Variables\n\nSet these in your MCP client configuration:\n\n| Variable | Default | Description |\n|----------|---------|-------------|\n| `TOON_THRESHOLD` | 0.7 | Minimum tabular eligibility (0-1) for TOON conversion |\n| `AUTO_CONVERT` | true | Whether to automatically convert files |\n| `CACHE_DIR` | ./.toon-cache | Directory for caching TOON files |\n\n### Threshold Guidelines\n\n- **0.5-0.6**: Aggressive (may convert mixed data)\n- **0.7** (default): Balanced compromise\n- **0.8-0.9**: Conservative (only highly uniform data)\n- **1.0**: Strict (only 100% uniform arrays)\n\n## Testing\n\n### Run Test Suite\n\n```bash\n./TEST_MCP_SERVER.sh\n```\n\nRuns 17 tests covering:\n- Data analysis accuracy\n- File optimization\n- Caching behavior\n- Token savings calculation\n- File exclusions\n\n### Interactive Inspector\n\n```bash\ncd toon-context-mcp\nnpm run inspector\n```\n\nTest the server tools interactively with your own files.\n\n## Performance\n\n| Metric | Value |\n|--------|-------|\n| **Conversion time** | 10-50ms for typical JSON files |\n| **Cache lookup** | <1ms for cached TOON files |\n| **Memory usage** | Minimal (streaming not required) |\n| **Token savings** | 30-60% for uniform tabular data |\n\n### Real-World Results\n\nFrom testing with sample data:\n\n| File | Original Tokens | TOON Tokens | Savings |\n|------|-----------------|-------------|---------|\n| users.json (5 items) | 220 | 84 | 61.8% |\n| users.json (100 items) | 3,171 | 1,245 | 60.7% |\n| products.json (50 items) | 1,856 | 798 | 57.0% |\n\n## Project Structure\n\n```\ntoon-context-mcp/\n├── src/\n│   ├── index.ts           # Main MCP server\n│   ├── inspector.ts       # Interactive testing tool\n│   ├── file-handler.ts    # File operations & conversion logic\n│   ├── data-analyzer.ts   # Data structure analysis\n│   └── toon-utils.ts      # TOON encoding/decoding\n├── build/                 # Compiled JavaScript\n├── examples/              # Test data\n├── config/                # Example configurations\n├── setup.sh               # Setup script\n├── README.md              # Server documentation\n└── package.json           # Dependencies\n```\n\n## Use Cases\n\n### Perfect For\n\n✅ **Uniform arrays of objects** - Same fields, primitive values  \n✅ **Large tabular datasets** - User lists, product catalogs, analytics data  \n✅ **API responses** - Consistent structured data  \n✅ **Database exports** - Table-like data structures  \n\n### Not Ideal For\n\n❌ **Deeply nested objects** - Complex hierarchical data  \n❌ **Non-uniform data** - Mixed structures  \n❌ **Small datasets** - Overhead not worth it (<10 items)  \n❌ **Configuration files** - Already excluded automatically  \n\n## Troubleshooting\n\n### Server Not Starting\n\n```bash\ncd toon-context-mcp\nrm -rf node_modules package-lock.json\nnpm install\nnpm run build\n```\n\n### Files Not Converting\n\n1. Check threshold: `TOON_THRESHOLD=0.7`\n2. Analyze file: `npm run inspector` → option 2\n3. Verify data is uniform (≥70% tabular)\n4. Check if file is excluded (system file)\n\n### Cached Files Out of Date\n\nCache automatically invalidates when source files change. To force refresh:\n\n```bash\nrm path/to/file.toon\n```\n\n### Agent Not Using Server\n\n1. Verify MCP configuration is correct\n2. Check server path is absolute\n3. Restart the MCP client\n4. Check server logs (stderr)\n\n## Documentation\n\n- **[MCP_SERVER.md](MCP_SERVER.md)** - Detailed MCP server guide with examples\n- **[toon-context-mcp/README.md](toon-context-mcp/README.md)** - Technical documentation\n- **[TOON Format Spec](https://github.com/toon-format/spec)** - Official TOON specification\n- **[Model Context Protocol](https://github.com/modelcontextprotocol)** - MCP specification\n\n## Why TOON?\n\nTOON (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.\n\n**Key Benefits:**\n- 📉 **Lower costs** - Fewer tokens = lower API costs\n- 🚀 **Longer context** - Fit more data in context window\n- ⚡ **Faster responses** - Less data to process\n- 🧠 **Better performance** - More efficient data representation\n\n## License\n\nMIT License - See [LICENSE](LICENSE) file\n\n## Acknowledgments\n\n- [TOON Format](https://github.com/toon-format/toon) by Johann Schopplich\n- [Model Context Protocol](https://github.com/modelcontextprotocol) by Anthropic\n- Built for integration with [Factory.ai Droid](https://factory.ai/) and other MCP-compatible tools\n"}