TOON MCP Server (Hasnain Ali47)

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 文件以获取详细信息。