toon-mcp-server 0.2.0
An MCP server and utilities for converting JSON and system prompts to TOON format and back.
License: MIT
Requires Python: >=3.9
Keywords: mcp, model-context-protocol, toon, llm, serialization

 ## 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:
 
 ```bash
 pip install toon-mcp-server
 ```
 
 For local development (in this repository), you can install in editable mode:
 
 ```bash
 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.
 
```python
from toon_mcp import (
    json_to_toon,
    toon_to_json,
    system_prompt_to_toon,
)
```
 
 ### JSON → TOON
 
 ```python
 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:
 
 ```python
 toon_text = json_to_toon(data, indent=2)
 ```
 
 ### TOON → JSON
 
 ```python
 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:
 
 ```python
 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:
 
 ```python
 {"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:
 
 ```bash
 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:
 
 ```json
 {
   "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:
 
 ```bash
 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.