datoon

io.github.andrii-suPublished by GitHub account andrii-suv1.9.1Updated Oct 24, 2026

Smart structured-data to TOON gateway: converts to TOON only when it saves LLM tokens.

VerifiedSTDIODesktop onlyDeveloper Tools Data & Analytics AI & ML

Server details

Identifier: io.github.andrii-su/datoon
Transport: STDIO
Runtime: Desktop only
Trust: Verified
Published: Sep 16, 2026

Security note

MCP servers receive tool arguments from a conversation and may perform external actions. Review what a server can do before you enable it, and give it only the access it needs.

The registry verified the GitHub account andrii-su for this listing. That does not show the account is the product's maker.

SourceWeft's checks cover whether the listing is complete and the endpoint answered; they do not review the server's code or what its tools do.

Add a badge to your README

Show readers this MCP server is listed on SourceWeft. The badge links to this page.

[![Listed on SourceWeft](https://sourceweft.com/badge/mcp/io.github.andrii-su%2Fdatoon.svg)](https://sourceweft.com/mcp/io.github.andrii-su%2Fdatoon?utm_source=readme&utm_medium=badge)

Overview

AI-generated overview

Converts structured data such as JSON, CSV, or YAML into TOON format for LLM prompts, but only when the conversion actually saves tokens.

What you can do: datoon is a local MCP server that turns structured data into TOON, a compact tabular text format, before it goes into a prompt. It exposes three tools: convert_json for full JSON conversion with policy gating, convert_text for CSV, YAML, XML, or JSONL text, and analyze_json for structure analysis only. A decision layer checks whether the payload is a uniform object array with enough rows and whether estimated token savings clear a threshold; if not, it returns the original data. Every result includes a report with the decision, a reason, and token estimates.
When to use it: Use it when prompts carry large, uniform tabular payloads — CSV exports, JSONL event logs, or API responses — and you want to cut payload tokens without risking a conversion that makes things worse. It is also useful when you want an explicit, logged reason for each format decision in a pipeline.
Requirements: Runs as a local process, typically via uvx from the PyPI package datoon with the mcp extra. Requires Python 3.12 or newer. TOON conversion itself requires Node.js with npx on PATH; analysis and format reading work without it. Optional extras add YAML, Excel, Parquet/ORC/Avro, Apple Numbers, and tiktoken-based token counting. No accounts, API keys, or environment variables are declared.

Before you install

Conversion calls the external TOON CLI through npx, so data being converted leaves the Python process for that subprocess. The --force flag bypasses the savings gate and can produce larger payloads. Token savings are estimates for the payload portion only, not full end-to-end model usage, and depend on data shape.

Installation

In SourceWeft

Open datoon in the dashboard and add it to a workspace.
Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

[Image]

datoon

smart structured-data→TOON gateway — converts only when it actually saves tokens

[Tests] [Pre-commit] [Release] [PyPI] [Python] [License: MIT]

Before/After • Install • What You Get • How It Works • Benchmarks • Full install guide

Raw structured data is often verbose in LLM prompts. TOON can save tokens — but blind conversion can also make payloads worse. datoon adds a decision layer: convert when structure and savings justify it, skip when they don't, and always explain why.

Supports JSON, CSV, JSONL, YAML, XML, Parquet, Avro, ORC, Excel, and Apple Numbers — auto-detected from file extension.

Before / After

JSON in the prompt (43 tokens)

json

{"users":[  {"id":1,"name":"Ada","role":"admin"},  {"id":2,"name":"Lin","role":"analyst"},  {"id":3,"name":"Grace","role":"viewer"}]}

{"users":[  {"id":1,"name":"Ada","role":"admin"},  {"id":2,"name":"Lin","role":"analyst"},  {"id":3,"name":"Grace","role":"viewer"}]}

datoon converts → TOON (24 tokens)

CSV from a data pipeline (111 tokens as JSON)

datoon auto-converts → TOON (24 tokens)

Same result. Zero JSON serialization in your code.

Non-uniform payload (26 tokens)

datoon skips → keeps JSON

No Node.js call. No silent corruption.

Same data. Right format. Always explained.

┌──────────────────────────────────────────────────┐│  PAYLOAD SAVINGS (auto avg)    ████░░░░░░   28%  ││  PAYLOAD SAVINGS (agent skill) ████████░░   62%  ││  DECISION ACCURACY             ██████████  100%  ││  HARMFUL CONVERSIONS BLOCKED   ██████████  100%  │└──────────────────────────────────────────────────┘

┌──────────────────────────────────────────────────┐│  PAYLOAD SAVINGS (auto avg)    ████░░░░░░   28%  ││  PAYLOAD SAVINGS (agent skill) ████████░░   62%  ││  DECISION ACCURACY             ██████████  100%  ││  HARMFUL CONVERSIONS BLOCKED   ██████████  100%  │└──────────────────────────────────────────────────┘

[!IMPORTANT] datoon saves payload tokens — the structured data portion of your prompt. Token savings depend on payload shape: uniform tabular data converts well; deeply nested or non-uniform structures are skipped. Every decision includes a reason so pipelines can log, debug, and trust the outcome.

Install

bash

# core (JSON, CSV, JSONL, XML — no extra deps)uv add datoonpip install datoon
# with YAML supportpip install "datoon[yaml]"
# with Excel supportpip install "datoon[excel]"
# with Parquet / ORC / Avro supportpip install "datoon[columnar]"
# with Apple Numbers supportpip install "datoon[numbers]"
# with tiktoken-based token countingpip install "datoon[tokens]"
# with MCP serverpip install "datoon[mcp]"
# everythingpip install "datoon[all]"

# core (JSON, CSV, JSONL, XML — no extra deps)uv add datoonpip install datoon
# with YAML supportpip install "datoon[yaml]"
# with Excel supportpip install "datoon[excel]"
# with Parquet / ORC / Avro supportpip install "datoon[columnar]"
# with Apple Numbers supportpip install "datoon[numbers]"
# with tiktoken-based token countingpip install "datoon[tokens]"
# with MCP serverpip install "datoon[mcp]"
# everythingpip install "datoon[all]"

Requires Python 3.12+. TOON conversion requires Node.js with npx in PATH — analysis and format reading work without it.

For Claude Code plugin, Codex, and MCP config → INSTALL.md.

What You Get

	What
`datoon` CLI	Auto-gate any supported format → TOON from terminal or scripts
Python API	`convert_json_for_llm()` + `read_tabular()` for any LLM pipeline
MCP Server	`convert_json`, `convert_text`, `analyze_json` tools for Claude Desktop, Cursor, Windsurf
Claude Code Plugin	`/datoon` in-session trigger, installs from GitHub in one command
Codex Plugin	Marketplace plugin — structured-data mode for Codex

Supported input formats

Format	Extension	Extra needed
JSON	`.json`	—
JSONL	`.jsonl`, `.ndjson`	—
CSV	`.csv`	—
XML	`.xml`	—
YAML	`.yaml`, `.yml`	`datoon[yaml]`
Excel	`.xlsx`, `.xls`	`datoon[excel]`
Parquet	`.parquet`	`datoon[columnar]`
Avro	`.avro`	`datoon[columnar]`
ORC	`.orc`	`datoon[columnar]`
Apple Numbers	`.numbers`	`datoon[numbers]`

How It Works

Detect format — from --format flag, file extension, or default to JSON for stdin
Read + normalize — parse source into list of row dicts; serialize to compact JSON
Analyze structure — uniform object arrays? acceptable depth? minimum rows?
Gate early — non-candidates skip before any CLI call; no Node.js overhead
Convert + estimate — TOON CLI runs, token savings calculated
Gate savings — below threshold → return JSON; above → return TOON with report

Every path returns a ConversionReport with decision, reason, and token estimates. Pipelines never get silent surprises.

Quick Start

JSON (stdin):

bash

echo '{"users":[{"id":1,"name":"Ada"},{"id":2,"name":"Lin"},{"id":3,"name":"Grace"}]}' | datoon --report-stdout

echo '{"users":[{"id":1,"name":"Ada"},{"id":2,"name":"Lin"},{"id":3,"name":"Grace"}]}' | datoon --report-stdout

CSV (auto-detected from extension):

JSONL:

YAML (requires datoon[yaml]):

Parquet (requires datoon[columnar]):

Explicit format override:

Force conversion (bypass gating — for experiments):

Python API

JSON conversion:

python

from datoon import convert_json_for_llm, ConversionConfig, DatoonError
config = ConversionConfig(min_savings_ratio=0.15, max_depth=6, min_uniform_rows=3)
try:    outcome = convert_json_for_llm(raw_json, config)except DatoonError as exc:    raise
# outcome.payload_text  — TOON or original JSON# outcome.report.decision  — "convert" | "skip"# outcome.report.reason    — human-readable explanationsend_to_model(outcome.payload_text)

from datoon import convert_json_for_llm, ConversionConfig, DatoonError
config = ConversionConfig(min_savings_ratio=0.15, max_depth=6, min_uniform_rows=3)
try:    outcome = convert_json_for_llm(raw_json, config)except DatoonError as exc:    raise
# outcome.payload_text  — TOON or original JSON# outcome.report.decision  — "convert" | "skip"# outcome.report.reason    — human-readable explanationsend_to_model(outcome.payload_text)

Any format via read_tabular:

python

import jsonfrom pathlib import Pathfrom datoon import read_tabular, convert_json_for_llm, ConversionConfig
# text formats: csv, jsonl, yaml, xmlrows = read_tabular("csv", text=csv_string)
# binary formats: excel, parquet, orc, avro, numbersrows = read_tabular("parquet", path=Path("data.parquet"))
json_text = json.dumps(rows, separators=(",", ":"))outcome = convert_json_for_llm(json_text, ConversionConfig())send_to_model(outcome.payload_text)

import jsonfrom pathlib import Pathfrom datoon import read_tabular, convert_json_for_llm, ConversionConfig
# text formats: csv, jsonl, yaml, xmlrows = read_tabular("csv", text=csv_string)
# binary formats: excel, parquet, orc, avro, numbersrows = read_tabular("parquet", path=Path("data.parquet"))
json_text = json.dumps(rows, separators=(",", ":"))outcome = convert_json_for_llm(json_text, ConversionConfig())send_to_model(outcome.payload_text)

Structure-only analysis (no Node.js required):

python

from datoon.analyzer import analyze_payloadfrom datoon.models import ConversionConfig
analysis = analyze_payload(parsed_data, ConversionConfig())print(analysis.is_candidate, analysis.reason)

from datoon.analyzer import analyze_payloadfrom datoon.models import ConversionConfig
analysis = analyze_payload(parsed_data, ConversionConfig())print(analysis.is_candidate, analysis.reason)

MCP Server

datoon ships an MCP server with three tools:

Claude Desktop / Cursor / Windsurf config:

json

{  "mcpServers": {    "datoon": {      "command": "uvx",      "args": ["--from", "datoon[mcp]", "datoon", "mcp"]    }  }}

{  "mcpServers": {    "datoon": {      "command": "uvx",      "args": ["--from", "datoon[mcp]", "datoon", "mcp"]    }  }}

Run locally:

Listed on the MCP Registry, Smithery, and Glama. See MARKETPLACES.md.

Claude Code Plugin

Install directly from GitHub:

Trigger in-session:

CLI Reference

Flag	Default	Description
`--format`	auto	Input format: `json`, `csv`, `jsonl`, `yaml`, `xml`, `excel`, `parquet`, `avro`, `orc`, `numbers`
`--force`	`false`	Bypass gating and minimum savings threshold
`--min-savings`	`0.15`	Minimum relative token savings required
`--max-depth`	`6`	Maximum nesting depth for auto-conversion
`--min-uniform-rows`	`3`	Minimum rows in uniform object arrays
`--timeout`	`30`	Seconds before TOON CLI call is aborted
`--report <path>`	—	Write JSON conversion report to file
`--report-stdout`	—	Print JSON conversion report to stderr
`-o <path>`	stdout	Output file path
`--version`	—	Print version and exit

Format is auto-detected from file extension. Use --format to override or when reading from stdin.

Benchmarks

bash

PYTHONPATH=src python benchmarks/run.py --dry-runPYTHONPATH=src python benchmarks/run.pyPYTHONPATH=src python benchmarks/run.py --update-readme

PYTHONPATH=src python benchmarks/run.py --dry-runPYTHONPATH=src python benchmarks/run.pyPYTHONPATH=src python benchmarks/run.py --update-readme

Why auto mode outperforms forced conversion

Auto mode avoids low-benefit and high-risk payloads (orders-nested, mixed-non-uniform) while matching forced TOON's average token count on suitable ones. Every decision comes with a reasoned report.

Dataset	JSON	TOON (forced)	Raw Saved	Auto	Auto Tokens	Auto Saved
users-small	54	40	25.9%	convert	40	25.9%
events-medium	219	162	26.0%	convert	162	26.0%
orders-nested	106	116	-9.4%	skip	106	0.0%
mixed-non-uniform	35	47	-34.3%	skip	35	0.0%
metrics-wide	142	103	27.5%	convert	103	27.5%
Average	111	94	7.1%	3/5 convert	89	15.9%

Forced conversion succeeded for 5/5 payloads.

Format conversion benchmark

Token savings when converting from common structured formats (CSV, JSONL, XML, YAML). Baseline is the JSON representation of the same data — what an LLM would receive without datoon.

Dataset	Format	JSON Tokens	TOON (forced)	Auto	Auto Tokens	Auto Saved
users-csv	csv	53	29	convert	29	45.3%
events-jsonl	jsonl	194	109	convert	109	43.8%
catalog-xml	xml	96	50	convert	50	47.9%
metrics-yaml	yaml	129	61	convert	61	52.7%
Average	—	118	62	4/4 convert	62	47.4%

Forced conversion succeeded for 4/4 payloads.

Agent skill evaluation

Artifact-based subagent comparison — identical analysis tasks, two modes:

with_skill: agent received the datoon skill and followed the conversion workflow.
without_skill: agent used JSON directly, no TOON or datoon.

3 payload sizes × 3 iterations = 18 total agent runs. Both modes: 100% correct answers.

Full report and raw outputs: benchmarks/agent_skill_eval/. Savings are payload-token estimates, not full end-to-end model-token usage.

Development

Contributor workflow: CONTRIBUTING.md. Maintainer/agent notes: CLAUDE.md.

Setup:

Tests:

bash

pytest -m "not integration"   # unit only (102 tests)pytest                        # with integration (requires Node.js + npx)

pytest -m "not integration"   # unit only (102 tests)pytest                        # with integration (requires Node.js + npx)

Skill sync + plugin metadata:

License

MIT

Source: README.md at commit 1579e24

Tools

SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

v1.9.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

Reached in the last 30 days25 pts
Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.
Auth declared10 pts
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
Tools listed15 pts
Answer tools/list without a credential, or ship a package that starts in a sandbox without one.
DescriptionRequired15 pts
Logo10 pts
Documentation15 pts
License10 pts

Scenario	JSON Baseline	Forced TOON	`datoon` Auto
Average tokens	77	50	50
Avg token saved	0.0%	26.8%	28.1%
Decision quality	n/a	Converts all	Converts `3/5`, skips harmful cases

Scenario	Avg JSON Tokens	Avg TOON Tokens	Avg Payload Saved
small	225	118	47.6%
medium	2,972	1,138	61.7%
large	17,757	6,673	62.4%

datoon

Overview

Installation

In SourceWeft

Other MCP clients

README

datoon

Before / After

JSON in the prompt (43 tokens)

datoon converts → TOON (24 tokens)

CSV from a data pipeline (111 tokens as JSON)

datoon auto-converts → TOON (24 tokens)

Non-uniform payload (26 tokens)

datoon skips → keeps JSON

Install

What You Get

Supported input formats

How It Works

Quick Start

Python API

MCP Server

Claude Code Plugin

CLI Reference

Benchmarks

Why auto mode outperforms forced conversion

Format conversion benchmark

Agent skill evaluation

Development

Links

License

Tools

Version history

Score