AI导哈

TOON格式转换工具

一个用于JSON数据和系统提示与TOON格式相互转换的Python工具库和MCP服务器，旨在减少与大型语言模型交互时的令牌使用。

  • by HasnainAli47
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 HasnainAli47/toon-mcp-server

使用说明

toon mcp服务器

MCP服务器和Python实用程序库，用于将JSON数据和系统提示转换为TOON格式或从TOON格式转换。

TOON（面向令牌的对象表示法）是一种紧凑的、人类可读的序列化格式，旨在减少与大型语言模型（LLM）交互时的令牌使用。它在使用通常使用的语法时保留了数据的结构 令牌效率比JSON高30-60%，尤其是表格或重复数据。

该项目提供：

  • 一个小型、类型良好的Python库 用于：
    • JSON↔ TOON转换。
    • 包装系统提示为TOON格式。
  • MCP stdio服务器 它将这些功能作为工具公开，随时可以从MCP兼容的主机（例如编辑器或编排层）使用。
  • PyPI就绪的包装和清晰的文档，所以你可以自信地与更广泛的Python社区分享这一点。

特性

  • JSON → TOON转换：使用以下命令将任何JSON序列化Python对象转换为TOON文本 toons 图书馆。
  • TOON → JSON转换：将TOON解析回可以序列化为JSON的Python对象。
  • 系统提示TOON包装器：用最小的、明确的TOON结构包装您的系统提示，以保持提示的结构化和令牌效率。
  • MCP stdio服务器:
    • 工具： convert_json_to_toon
    • 工具： convert_toon_to_json
    • 工具： convert_system_prompt_to_toon
  • 清洁、简单的API 具有适合库使用的类型提示和文档字符串。

安装

一旦发布到PyPI，您将能够使用以下方式安装它：

pip install toon-mcp-server

对于本地开发（在此存储库中），您可以在可编辑模式下安装：

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

这将安装：

  • 这 toon_mcp Python包。
  • 这 toon-mcp-server 控制台脚本，用于运行MCP stdio服务器。

图书馆使用情况

主要公众API居住在 toon_mcp 并从以下国家再出口 __init__.py 为了方便起见。

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)
  • 输入：任何JSON串行Python对象(dict, list, str等等）。
  • 输出：可以发送到LLM或存储在磁盘上的TOON字符串。

您可以选择请求特定的缩进级别以提高可读性：

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
  • 输入：TOON文本（字符串）。
  • 输出：Python对象（通常 dict 或 list)然后你可以传递给 json.dumps，您的LLM客户端或其他逻辑。

系统提示→ TOON

系统提示通常很大，并且对许多请求重复出现。此帮助程序将您的系统提示包装在一个最小的TOON文档中：

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)

从概念上讲，这相当于序列化一个结构，例如：

{"system_prompt": system_prompt}

但采用TOON格式，对于较大的提示，它往往比原始JSON更紧凑。

MCP服务器

MCP服务器在 toon_mcp.server 并作为 toon-mcp-server 控制台脚本。

在引擎盖下，它使用官方 mcp Python库并在stdio上运行：

  • 它公开了三个工具：
    • convert_json_to_toon
    • convert_toon_to_json
    • convert_system_prompt_to_toon
  • 它旨在由MCP兼容的主机（例如编辑器、CLI编排器或其他工具）启动。

工具

  • convert_json_to_toon

    • 输入: payload JSON可序列化结构（MCP通常会将其作为JSON对象发送）。
    • 输出：TOON字符串。

  • convert_toon_to_json

    • 输入: toon_text –TOON格式的字符串。
    • 输出：解码的Python结构（主机可以序列化回JSON）。

  • convert_system_prompt_to_toon

    • 输入: prompt –纯文本系统提示。
    • 输出：TOON字符串包装提示（与兼容 toon_to_system_prompt 在图书馆）。

手动运行服务器

安装软件包后：

toon-mcp-server

这将启动stdio上的MCP服务器（通常由MCP主机启动，而不是手动启动）。

主机配置示例（概念性）

具体配置因主机而异，但典型的配置可能如下：

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

请参阅MCP主机的文档，了解在何处以及如何指定此配置。

项目布局

  • pyproject.toml：为PyPI构建配置和元数据。
  • src/toon_mcp/__init__.py：公共API导出。
  • src/toon_mcp/codec.py：核心转换功能。
  • src/toon_mcp/server.py：MCP stdio服务器和工具定义。
  • tests/：转换和快速处理的基本测试。

设计说明

  • TOON正式实施：该项目有意将TOON解析和序列化委托给 toons 库，它在Rust中实现并反映了标准 json 模块API。这使实现保持了小型化、可预测性和高性能。
  • 简单、明确的API:
    • json_to_toon / toon_to_json 对任意JSON序列化结构进行操作。
    • system_prompt_to_toon 关注系统提示用例，保持结构清晰({"system_prompt": ...})同时受益于TOON语法。
  • MCP头等舱：MCP服务器在 toon_mcp.server，并通过 toon-mcp-server 控制台脚本，以便主机可以轻松启动它。

测试

安装开发依赖关系后，您可以使用以下命令运行测试：

pytest

基本测试包括：

  • 往返JSON→ TOON → JSON.

我们鼓励您为您的特定用例和数据形状添加更多测试。

错误处理

库和MCP工具是防御性的，将 明显的错误 误用时：

  • json_to_toon / convert_json_to_toon

    • 期待a JSON严重对象 （dict、list、str、int、float、bool或None）。
    • 如果对象不能序列化，则会引发 TypeError 并显示一条消息，解释失败的类型及其原因。
    • 如果 indent 不是整数或 None一 TypeError 描述了错误的类型。

  • toon_to_json / convert_toon_to_json

    • 期待a 包含TOON数据的字符串.
    • 如果传递了一个非字符串值，它们将引发 TypeError.
    • 如果TOON文本无效，则会引发 ValueError 附有底层解析错误消息。

  • system_prompt_to_toon / convert_system_prompt_to_toon

    • 期待a 普通字符串系统提示.
    • 如果传递了一个非字符串值，它们将引发 TypeError （包装成 ValueError 在MCP层）显示描述不正确类型的消息。

这些消息旨在在直接使用Python和通过MCP主机调用工具时很好地显示出来。

版本控制

该项目如下 语义版本控制:

  • 重大：打破变化。
  • 次要的：添加向后兼容的功能。
  • 补丁：向后兼容的错误修复和小改进。

贡献

欢迎投稿！

  • 问题：使用GitHub Issues报告错误或请求功能。
  • 拉取请求:
    • 保持变更的重点并做好记录。
    • 添加或更新新行为的测试。
    • 维护类型提示和文档字符串。

许可证

该项目根据 MIT许可证。请参阅 LICENSE 文件以获取详细信息。

相关 MCP