json-shaper-lite

[Tidy Byte Tools]

json-shaper-lite

[License: MIT] [Python 3.10+] [MCP server]

Free tool that turns key: value notes, CSV/TSV and Markdown tables into clean JSON. Need app logs or US addresses parsed too? The paid version does that: json-shaper on Gumroad

Plain code, not AI, so the same text always gives the same JSON. Runs on your own computer. MIT license. Works with Python 3.10 and newer, on Windows, Mac and Linux.

Install

pip install json-shaper-lite

Or use pipx, which keeps it in its own space:

pipx install json-shaper-lite

Want the newest code from GitHub instead?

pip install git+https://github.com/tidybytetools/json-shaper-lite

Or just download json_shaper_lite.py and run it with python3. That one file uses only Python's standard library. (Installing with pip also adds the mcp package, which the MCP server needs.)

Use it

printf 'Name: Ada\nAge: 36\nActive: yes' | json-shaper-litejson-shaper-lite export.csvjson-shaper-lite notes.md --format markdownjson-shaper-lite export.csv --json      # {"ok": true, "format": "csv", "data": [...]}

Output:

{"name": "Ada", "age": 36, "active": true}

Numbers come out as numbers, yes/no and true/false as booleans, and empty or "null" as null. The format is detected for you, or you can set it with --format kv|csv|markdown.

From Python:

from json_shaper_lite import shapeshape("x,y\n1,2")  # {'format': 'csv', 'data': [{'x': 1, 'y': 2}]}

When you run it in a terminal it prints one short line about the paid version to stderr after the result. It never goes into your JSON output, it only shows when you are looking at a terminal, and --quiet turns it off.

Known limits

• It makes flat JSON. It does not flatten or unflatten nested JSON. For that, use a tool like flatten-json.
• Types are a best guess. A value like 007 or a zip code can turn into a number. Fix those by hand after.
• One table per run. Two Markdown tables in one file get mixed together. Split them first.
• No app logs or addresses. Those are in the paid version.

How it compares to other free tools

If your data is already JSON and just too nested, flatten-json is the better pick.

Use it from Claude Desktop or Cursor (MCP)

There is a small free MCP server built in. It gives your AI app two tools. Both only read. They never write or change files, and they never use the internet. It needs uv.

Run it by hand to check it starts (it waits quietly for an app to talk to it):

uvx json-shaper-lite mcp

Claude Desktop (claude_desktop_config.json) or Cursor (~/.cursor/mcp.json):

{  "mcpServers": {    "json-shaper-lite": {      "command": "uvx",      "args": ["json-shaper-lite", "mcp"]    }  }}

uvx --from json-shaper-lite json-shaper-lite-mcp starts the same server.

Tools:

• shape_text_to_json(text, format="auto"): for text in the chat.
• shape_file_to_json(path, format="auto"): for a text file on your computer (.txt, .csv, .tsv, .md, up to 5 MB).

Both return {"format": "csv", "data": [...]}. format can be auto, kv, csv or markdown.

For AI agents

• Use when: you have plain text in key: value lines, CSV/TSV, or a Markdown table and need typed JSON.
• Don't use when: the input is already JSON, it's app logs, or it's nested data. Use the paid version for logs.
• Input: text on stdin or a file path. Optional --format kv|csv|markdown.
• MCP: uvx json-shaper-lite mcp gives two read-only tools, shape_text_to_json and shape_file_to_json.
• Output: with --json, one object: {"ok": true, "format": "csv", "data": [...]}. On error ok is false. Exit code 0 ok, 1 error.
• Hint lines go to stderr only, and only in a terminal, so stdout is always clean JSON. See also llms.txt.

Lite vs paid

Tests

pip install "mcp>=1.10,<2"python3 -m unittest discover tests

The MCP tests are skipped if mcp is not installed.

License

MIT. See LICENSE.