toon-mcp-server 0.2.0

toon-mcp-server

An MCP server and Python utility library for converting JSON data and system prompts to and from TOON format.

TOON (Token‑Oriented Object Notation) is a compact, human‑readable serialization format designed to reduce token usage when interacting with Large Language Models (LLMs). It preserves the structure of your data while using a syntax that is often 30–60% more token‑efficient than JSON, especially for tabular or repetitive data.

This project provides:

• A small, well‑typed Python library for:
  • JSON ↔ TOON conversion.
  • Wrapping system prompts in TOON format.
• An MCP stdio server that exposes these capabilities as tools, ready to be used from MCP‑compatible hosts (e.g. editors or orchestration layers).
• PyPI‑ready packaging and clear documentation, so you can confidently share this with the wider Python community.

---

Features

• JSON → TOON conversion: Convert any JSON‑serialisable Python object into TOON text using the toons library.
• TOON → JSON conversion: Parse TOON back into Python objects that you can serialise as JSON.
• System prompt TOON wrapper: Wrap your system prompt in a minimal, explicit TOON structure to keep prompts structured and token‑efficient.
• MCP stdio server:
  • Tool: convert_json_to_toon
  • Tool: convert_toon_to_json
  • Tool: convert_system_prompt_to_toon
• Clean, simple API with type hints and docstrings suitable for library use.

---

Installation

Once published to PyPI, you will be able to install it with:

pip install toon-mcp-server

For local development (in this repository), you can install in editable mode:

cd path/to/this/repo
pip install -e .

This will install:

• The toon_mcp Python package.
• The toon-mcp-server console script, which runs the MCP stdio server.

---

Library Usage

The main public API lives in toon_mcp and is re‑exported from __init__.py for convenience.

from toon_mcp import (
    json_to_toon,
    toon_to_json,
    system_prompt_to_toon,
)

JSON → TOON

from toon_mcp import json_to_toon

data = {
    "user": {"id": 123, "name": "Alice"},
    "messages": [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Explain TOON format in simple terms."},
    ],
}

toon_text = json_to_toon(data)
print(toon_text)

• Input: Any JSON‑serialisable Python object (dict, list, str, etc.).
• Output: A TOON string that can be sent to an LLM or stored on disk.

You can optionally request a specific indentation level for readability:

toon_text = json_to_toon(data, indent=2)

TOON → JSON

from toon_mcp import toon_to_json

obj = toon_to_json(toon_text)
# `obj` is now a standard Python structure that can be serialised as JSON

• Input: TOON text (string).
• Output: Python object (typically dict or list) that you can then pass to json.dumps, your LLM client, or other logic.

System prompt → TOON

System prompts are often large and repeated for many requests. This helper wraps your system prompt in a minimal TOON document:

from toon_mcp import system_prompt_to_toon

system_prompt = (
    "You are a senior Python engineer. "
    "Answer clearly, use type hints, and explain important design decisions."
)

toon_prompt = system_prompt_to_toon(system_prompt)
print(toon_prompt)

Conceptually, this is equivalent to serialising a structure like:

{"system_prompt": system_prompt}

but in TOON form, which tends to be more compact than raw JSON for larger prompts.

MCP Server

The MCP server is implemented in toon_mcp.server and is installed as the toon-mcp-server console script.

Under the hood it uses the official mcp Python library and runs over stdio:

• It exposes three tools:
  • convert_json_to_toon
  • convert_toon_to_json
  • convert_system_prompt_to_toon
• It is meant to be launched by an MCP‑compatible host (e.g. an editor, a CLI orchestrator, or other tooling).

Tools

• convert_json_to_toon

  • Input: payload – JSON‑serialisable structure (MCP will usually send this as a JSON object).
  • Output: TOON string.

• convert_toon_to_json

  • Input: toon_text – TOON‑formatted string.
  • Output: Decoded Python structure (serialisable back to JSON by the host).

• convert_system_prompt_to_toon

  • Input: prompt – plain text system prompt.
  • Output: TOON string wrapping the prompt (compatible with toon_to_system_prompt in the library).

Running the server manually

After installing the package:

toon-mcp-server

This will start the MCP server on stdio (it is meant to be started by an MCP host, not usually by hand).

Example host configuration (conceptual)

Exact configuration varies per host, but a typical configuration might look like:

{
  "mcpServers": {
    "toon-mcp-server": {
      "command": "toon-mcp-server",
      "args": []
    }
  }
}

Consult your MCP host's documentation to see where and how to specify this configuration.

---

Project Layout

• pyproject.toml: Build configuration and metadata for PyPI.
• src/toon_mcp/__init__.py: Public API exports.
• src/toon_mcp/codec.py: Core conversion functions.
• src/toon_mcp/server.py: MCP stdio server and tool definitions.
• tests/: Basic tests for conversions and prompt handling.

---

Design Notes

• Official TOON implementation: This project deliberately delegates TOON parsing and serialisation to the toons library, which is implemented in Rust and mirrors the standard json module API. This keeps the implementation small, predictable, and performant.
• Simple, explicit API:
  • json_to_toon / toon_to_json operate on arbitrary JSON‑serialisable structures.
  • system_prompt_to_toon focuses on the system prompt use‑case, keeping the structure obvious ({"system_prompt": ...}) while benefitting from TOON syntax.
• MCP first‑class: The MCP server is implemented once, in toon_mcp.server, and exported through the toon-mcp-server console script so hosts can launch it easily.

---

Testing

After installing development dependencies, you can run tests with:

pytest

Basic tests cover:

• Round‑trip JSON → TOON → JSON.

You are encouraged to add more tests for your specific use‑cases and data shapes.

---

Error handling

The library and MCP tools are defensive and will give clear, explicit errors when misused:

• json_to_toon / convert_json_to_toon

  • Expect a JSON‑serialisable object (dict, list, str, int, float, bool, or None).
  • If the object cannot be serialised, they raise TypeError with a message explaining what type failed and why.
  • If indent is not an integer or None, a TypeError is raised describing the wrong type.

• toon_to_json / convert_toon_to_json

  • Expect a string containing TOON data.
  • If a non‑string value is passed, they raise TypeError.
  • If the TOON text is invalid, they raise ValueError with the underlying parse error message attached.

• system_prompt_to_toon / convert_system_prompt_to_toon

  • Expect a plain string system prompt.
  • If a non‑string value is passed, they raise TypeError (wrapped as a ValueError at MCP layer) with a message describing the incorrect type.

These messages are designed to surface nicely in both direct Python usage and when the tools are called through an MCP host.

---

Versioning

This project follows semantic versioning:

• MAJOR: Breaking changes.
• MINOR: Backwards‑compatible feature additions.
• PATCH: Backwards‑compatible bug fixes and small improvements.

---

Contributing

Contributions are welcome!

• Issues: Use GitHub Issues to report bugs or request features.
• Pull Requests:
  • Keep changes focused and well‑documented.
  • Add or update tests for new behaviour.
  • Maintain type hints and docstrings.

---

License

This project is licensed under the MIT License. See the LICENSE file for details.