toon-mcp by kweinmeister - MCP Server

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:

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

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

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"]
    }
  }
}
```
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