TOON MCP Server

A Model Context Protocol (MCP) server that provides tools for encoding and decoding TOON (Token-Oriented Object Notation).

TOON is a compact, human-readable format designed to represent JSON data using significantly fewer tokens, making it ideal for LLM prompts and context optimization.

👉 Learn more about the format at toonformat.dev

Features

This server exposes two core tools to MCP clients (specifically tested with Gemini CLI):

• encode_toon: Converts JSON strings into TOON format to save tokens.
• decode_toon: Converts TOON formatted text back into standard JSON.

Usage

Quick Start with Gemini CLI

To use this server with the Gemini CLI, follow these steps:

1. Install Gemini CLI (if you haven't already):

   npm install -g @google/gemini-cli@latest

2. Configure the MCP Server: You can register the server by creating or editing your Gemini settings file, typically located at ~/.gemini/settings.json (Global) or .gemini/settings.json (Project-local).

   Add the following configuration:

   {
     "mcpServers": {
       "toon": {
         "command": "npx",
         "args": ["-y", "git+https://github.com/kweinmeister/toon-mcp.git"]
       }
     }
   }

3. Run Gemini CLI: Start the CLI interface. The tools should now be available to the model.

   gemini

Tools

1. encode_toon

Converts JSON data into the compact TOON format.

Parameters:

| Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | json | string | Required | The JSON data (serialized as a string) to encode. | | indent | number | 2 | Number of spaces for indentation. | | delimiter | string | , | Delimiter for arrays/rows. Options: , (comma), \t (tab), \| (pipe). | | keyFolding | string | "off" | Collapse single-key wrapper chains (e.g., a.b.c). Options: "off", "safe". | | flattenDepth | number | Infinity | Maximum depth to apply key folding. | | replacer | (string\|number)[] | undefined | Array of properties to include in the output. |

Example Prompt in Gemini CLI:

"Use the encode_toon tool to convert this JSON into TOON format: {"users": [{"id": 1, "name": "Alice"}, {"id": 2, "name": "Bob"}]}"

Output:

users[2]{id,name}:
  1,Alice
  2,Bob

2. decode_toon

Parses TOON formatted text back into standard JSON.

Parameters:

| Parameter | Type | Default | Description | | :--- | :--- | :--- | :--- | | toon | string | Required | The TOON formatted string to decode. | | strict | boolean | true | Enforce strict validation (e.g., checking declared array lengths). | | expandPaths | string | "off" | Reconstruct dotted keys into nested objects. Options: "off", "safe". | | indent | number | 2 | Number of spaces for indentation. |

Transports

This server supports both HTTP Server-Sent Events (SSE) and Standard IO (stdio).

HTTP / SSE (Default)

Useful for remote deployments (like Cloud Run) or web-based MCP clients.

# Starts on port 8080 by default
npm start

# Custom port
npm start -- --port 3000

Stdio

Used by local clients like Gemini CLI.

npm run start:stdio

Development

Installation

git clone https://github.com/kweinmeister/toon-mcp
cd toon-mcp
npm install

Testing

Run the unit tests to ensure the server tools are functioning correctly:

npm test

Debugging with MCP Inspector

You can use the MCP Inspector to inspect and test the server's tools interactively via a web interface.

npx fastmcp inspect index.ts

Building & Linting

# Linting
npx biome check .

# Type checking
npx tsc --noEmit