Skip to main content
Glama
kweinmeister

toon-mcp

by kweinmeister
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Hybrid

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.

Related MCP server: TOON MCP Server

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

Available Tools

2 tools
decode_toonB

Convert TOON formatted text back into standard JSON.

ParametersJSON Schema
NameRequiredDescriptionDefault
toonYesThe TOON formatted string to decode.
indentNoNumber of spaces for indentation.
strictNoEnforce strict validation (e.g. array lengths). Defaults to true.
expandPathsNoReconstruct dotted keys into nested objects. Defaults to 'off'.

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description must carry the full burden of behavioral disclosure. The description only states the conversion outcome without detailing error handling, return format, or side effects. As a decode tool, it is likely safe, but no explicit confirmation is given.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is direct and to the point. Every word contributes meaning, with no unnecessary elaboration.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given that there is no output schema and no annotations, the description should explain what the returned JSON looks like or any constraints. It fails to mention the return format, error conditions, or behavior of optional parameters, leaving gaps for the agent.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers all 4 parameters with descriptions, achieving 100% coverage. The tool description adds no additional context beyond what the schema provides, so it meets the baseline of 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the function: convert TOON formatted text into standard JSON. The verb 'Convert' and the specific resource 'TOON formatted text' make the purpose unambiguous, and the sibling 'encode_toon' implies the reverse operation, providing clear differentiation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies when to use (when you have TOON text and need JSON), but lacks explicit guidance on when not to use or mention of alternatives beyond the sibling. No exclusions or context hints are provided, so the usage guidance is merely implied.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

encode_toonB

Convert JSON data into compact TOON format to save tokens.

ParametersJSON Schema
NameRequiredDescriptionDefault
jsonYesThe JSON data (as a string) to encode into TOON format.
indentNoNumber of spaces for indentation. Defaults to 2.
replacerNoArray of properties to include in the output. If not provided, all properties are included.
delimiterNoDelimiter for array values (comma, tab, or pipe). Defaults to comma.
keyFoldingNoCollapse single-key wrapper chains into dotted paths. Defaults to 'off'.
flattenDepthNoMaximum depth for key folding. Defaults to Infinity.

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description bears full responsibility for behavioral disclosure. It only states the conversion purpose without any details on side effects, idempotency, error handling, or permissions.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise with a single front-loaded sentence. However, it could benefit from minimal structural elements to improve scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The description lacks details on the return format (expected to be a string in TOON format) and does not address error conditions. Given the absence of output schema and 6 parameters, the description is incomplete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema descriptions cover 100% of parameters. The description adds no additional meaning beyond the schema, so baseline score of 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb (Convert), resource (JSON data into compact TOON format), and the benefit (save tokens). It effectively distinguishes from the sibling tool decode_toon.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage when one wants to convert JSON to TOON format to save tokens, but lacks explicit guidance on when to use versus alternatives. No mention of prerequisites or when not to use.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 2 tool updatesv1.0.0
    • First observeddecode_toon
    • First observedencode_toon
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A3.9/5.0

Scored across 2 tools

Disambiguation5/5

The two tools have clearly distinct purposes: one converts TOON to JSON, the other JSON to TOON, with no overlap in functionality.

Naming Consistency5/5

Both tools follow a consistent verb_noun pattern (decode_toon, encode_toon), making the action and target clear.

Tool Count5/5

With exactly two tools covering the bidirectional conversion, the count is perfectly scoped for the domain; each tool is essential.

Completeness5/5

The tool set fully covers the conversion domain with both directions present, leaving no gaps in functionality.

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • TOON MCP Server

    HasnainAli47
    A
    license
    Not graded
    quality
    D
    maintenance
    Converts JSON data and system prompts to and from TOON (Token-Oriented Object Notation) format, reducing token usage by 30-60% when interacting with LLMs while preserving data structure.
    MIT

  • TOON MCP Server

    elminson
    A
    license
    A
    quality
    D
    maintenance
    Enables users to convert structured data into Token-Oriented Object Notation (TOON) to reduce LLM token usage and costs by up to 70%. It provides tools for encoding, decoding, and analyzing data formats like JSON, CSV, and XML to optimize prompt efficiency.
    4
    5 npm
    3
    MIT

  • TOONer

    chaindead
    A
    license
    Not graded
    quality
    C
    maintenance
    MCP proxy that wraps any MCP server and transparently converts JSON responses in tools/call to TOON format — a token-efficient alternative to JSON optimized for LLMs (~40% fewer tokens).
    21
    MIT