json-shaper-lite

json-shaper-lite

免费工具，可将 key: value 笔记、CSV/TSV 和 Markdown 表格转换为整洁的 JSON。 还需要解析应用日志或美国地址？付费版本可以做到：在 Gumroad 上获取 json-shaper

它使用普通代码而非 AI，因此相同文本始终会生成相同的 JSON。可在你自己的计算机上运行。采用 MIT 许可证。支持 Windows、Mac 和 Linux 上的 Python 3.10 及更高版本。

安装

pip install json-shaper-lite

或者使用 pipx，它会将程序安装在独立环境中：

pipx install json-shaper-lite

想要直接使用 GitHub 上的最新代码？

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

也可以只下载 json_shaper_lite.py，然后用 python3 运行。这个文件仅使用 Python 标准库。（通过 pip 安装也会添加 mcp 包，这是 MCP 服务所需的。）

使用方法

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

输出：

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

数字会输出为数字，yes/no 和 true/false 会输出为布尔值，空值或 "null" 会输出为 null。程序会自动检测格式，也可以通过 --format kv|csv|markdown 指定。

在 Python 中使用：

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

在终端中运行时，它会在结果输出后向 stderr 打印一行关于付费版本的简短信息。该信息不会进入 JSON 输出，只会在终端中显示；使用 --quiet 可以关闭。

已知限制

• 它生成的是扁平 JSON。 不会展平或还原嵌套 JSON。此类需求可使用 flatten-json 等工具。
• 类型判断只是尽力猜测。 像 007 或邮政编码这样的值可能会被转换为数字。之后需要手动修正。
• 每次运行只能处理一个表格。 一个文件中的两个 Markdown 表格会混在一起。请先拆分。
• 不支持应用日志或地址。 这些功能包含在付费版本中。

与其他免费工具的比较

	json-shaper-lite	flatten-json	csvkit csvjson	pandas
主要用途	混乱文本 → JSON	嵌套 JSON → 扁平 JSON（也可还原）	CSV → JSON	完整的数据工具集
安装大小	一个文件（为 MCP 服务安装时会添加 mcp）	小	中	大
key: value 笔记	支持	不支持	不支持	不支持
Markdown 表格	支持	不支持	不支持	不支持，内置功能不支持
CSV/TSV	支持	不支持	支持	支持
猜测数字和 true/false	支持	不支持	支持	支持
嵌套 JSON 展平/还原	不支持	支持	不支持	支持（json_normalize）
面向 AI 应用的 MCP 服务	支持	不支持	不支持	不支持

如果你的数据已经是 JSON，只是嵌套层级太多，那么 flatten-json 是更好的选择。

在 Claude Desktop 或 Cursor 中使用（MCP）

内置了一个小型免费 MCP 服务，可为你的 AI 应用提供两个工具。两者都只读取数据，不会写入或更改文件，也不会使用互联网。需要安装 uv。

手动运行以检查是否能启动（它会安静地等待应用与其通信）：

uvx json-shaper-lite mcp

Claude Desktop（claude_desktop_config.json）或 Cursor（~/.cursor/mcp.json）：

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

uvx --from json-shaper-lite json-shaper-lite-mcp 会启动同一个服务。

工具：

• shape_text_to_json(text, format="auto")：处理聊天中的文本。
• shape_file_to_json(path, format="auto")：处理计算机上的文本文件（.txt、.csv、.tsv、.md，最大 5 MB）。

两者都会返回 {"format": "csv", "data": [...]}。format 可以是 auto、kv、csv 或 markdown。

面向 AI Agent

• 适用场景： 你有按 key: value 格式排列的纯文本、CSV/TSV 或 Markdown 表格，并且需要将其转换为类型化 JSON。
• 不适用场景： 输入已经是 JSON、是应用日志或是嵌套数据。处理日志请使用付费版。
• 输入： 从 stdin 或文件路径输入文本。可选参数 --format kv|csv|markdown。
• MCP： uvx json-shaper-lite mcp 提供两个只读工具：shape_text_to_json 和 shape_file_to_json。
• 输出： 使用 --json 时，输出一个对象：{"ok": true, "format": "csv", "data": [...]}。出错时 ok 为 false。退出代码：成功为 0，出错为 1。
• 提示信息仅会输出到 stderr，且仅在终端中输出，因此 stdout 始终是干净的 JSON。另请参阅 llms.txt。

Lite 版与付费版

	lite（免费）	json-shaper
key: value 记事、CSV/TSV、Markdown 表格	是	是
应用日志（时间戳、级别、消息、key=value 字段）	否	是
单行美国地址拆分器	否	是
用于脚本和 AI Agent 的 tool.json 清单	否	是

测试

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

如果未安装 mcp，则会跳过 MCP 测试。

许可证

MIT。详见 LICENSE。